REST API overview

The REST API is served from a single base URL:

https://app.reechee.io/api/v1

It is the source of truth for the platform - the MCP server is a thin wrapper over these same endpoints.

Authentication

Every endpoint except GET /health needs a credential: an API key (on every plan, starting with pay-as-you-go) or an OAuth Connect token, sent as a bearer token:

curl "https://app.reechee.io/api/v1/credit-balance" \
  -H "Authorization: Bearer rch_live_your_key_here"

Create and revoke keys in the app under Settings → API keys. No account yet? Start free at app.reechee.io, no card needed. A call without a key gets 401 unauthorized with a pointer to sign up. See the Authentication guide for details.

Response envelope

Every response is a JSON envelope. Success:

{
  "success": true,
  "data": { },
  "meta": { }
}

Failure:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

data is the payload (an object or an array). meta is optional and carries things like pagination on list endpoints. error.details is present only on some errors.

Pagination

List endpoints are page-based (1-indexed). Pass page and page_size (max 100, default 20). The response’s meta.pagination tells you whether to keep going:

{ "page": 1, "page_size": 20, "has_more": true }

Full review evidence

For review-sourced opportunities, GET /opportunities/{id} includes four nullable strings under data.review: review_title, pros, cons, and general_comments. These are the full stored fields, not an AI summary. Missing source fields stay null; a partial review does not produce invented replacement text. The opportunity list does not include these fields. On pricing version 2, all four fields are null until your team reveals the reviewer, including when the company is already known from another reviewer. A successful POST /opportunities/{id}/reveal returns the authorized fields under data.opportunity.review; later detail reads keep returning them. Revealing the same reviewer again returns the evidence with credits_used: 0. Legacy pricing version 1 retains access to stored review text without a reviewer reveal. For example, a revealed review with no stored general comment can contain:

{
  "review_title": "Useful reporting, slow exports",
  "pros": "The saved reports help our weekly review.",
  "cons": "Large exports take too long.",
  "general_comments": null
}

This is a fragment of review, not the entire response. Before a pricing-v2 reveal, the same four keys are present with null values. Existing organization and source access rules still apply: knowing an opportunity ID does not grant access to another team’s evidence. Email, phone, and buying-committee unlocks retain their separate gates.

Errors

Errors use a stable machine code plus a human message. The HTTP status matches the code, except that internal_error is also returned with 503:

Status	`code`	When
400	`invalid_request`	Malformed parameters or body.
401	`unauthorized`	Missing, invalid, revoked, or expired API key.
402	`payment_required`	Not enough credits for a credit-spending action.
403	`forbidden`	A limit was reached (e.g. the plan’s product cap).
404	`not_found`	Unknown resource id.
429	`rate_limited`	Rate limit exceeded - see the `Retry-After` header.
500	`internal_error`	Something went wrong on our side.
503	`internal_error`	A dependency is unavailable (the database, or report generation). On a credit action, the message says whether a credit was charged. Retry later.

See the error reference and rate limits for the full story.

Endpoints

Browse the full endpoint reference in this section - each page has request parameters, schemas, and a live “Try it” playground.

​Authentication

​Response envelope

​Pagination

​Full review evidence

​Errors

​Endpoints