---
name: sourcey
description: Search and verify startup programs with Sourcey's immutable, provenance-bound registry. Use when an agent needs to discover startup credits, discounts, free tiers, deals, or agent readiness profiles; read the State of Startup Credits or State of Agent Readiness report; check structured eligibility; inspect freshness, disputes, evidence, revisions, or change history; consume the Sourcey HTTP API, OpenAPI contract, JSON Feed, or hosted MCP server; or cite an exact Sourcey release without applying for or redeeming an offer.
---

# Sourcey

Use Sourcey as a read-only public record. Treat every answer as a projection of one immutable release,
not as timeless truth.

## Connect

- Website: `https://sourcey.com`
- OpenAPI: `https://api.sourcey.com/openapi.yml`
- API origin: `https://api.sourcey.com`
- Companies dataset: `https://sourcey.com/companies.json`
- Startup credits dataset: `https://sourcey.com/startup-credits.json`
- Agent Readiness dataset: `https://sourcey.com/agent-readiness.json`
- State of Startup Credits report: `https://sourcey.com/reports/startup-credits` (JSON:
  `https://sourcey.com/reports/startup-credits.json`)
- State of Agent Readiness report: `https://sourcey.com/reports/agent-readiness` (JSON:
  `https://sourcey.com/reports/agent-readiness.json`)
- MCP manifest: `https://mcp.sourcey.com/mcp.json`
- MCP transport: `https://mcp.sourcey.com/mcp`
- Change feed: `https://api.sourcey.com/feed.json`
- Repository: `https://github.com/sourcey/startup-credits`

Prefer MCP for tool-native discovery and the HTTP API for deterministic integration. Generate a
client from OpenAPI when a typed client is useful; do not depend on an unofficial SDK. Use the
focused datasets for complete bulk reads: join them by immutable IDs and require matching
`release_id` and `artifact_sha256` values.

## Preserve the trust boundary

1. Record `release_id` and `artifact_sha256` from every API result.
2. Keep stable IDs and revision digests in stored state; use slugs only for human navigation.
3. Report evidence freshness, dispute state, vendor attestation, Entity identity assurance, Offer
   terms assurance, and lifecycle independently with material claims.
4. Say when eligibility is unknown. Never convert missing criteria into approval.
5. Treat offer value as the structured value in the response, including units and limits.
6. Re-check the current revision before presenting time-sensitive terms.
7. Never claim that Sourcey applied for, redeemed, reserved, or guaranteed an offer.
8. Ask before following a redemption URL or taking an action outside Sourcey.

## Choose a workflow

### Find programs

1. Search offers with `GET /v1/search/offers?q=...` or call the search tool advertised by MCP
   `tools/list` with a query, vendor list, or category list plus typed company facts.
2. Treat each result as an Entity-owned Offer. When `program_id` is present, read that adjacent
   Program as the Offer's named scheme; never synthesize a Program for a standalone Offer.
3. Filter results using structured category, lifecycle, economics, eligibility, and provenance.
4. Read the Program and shortlisted Offer by stable ID or current slug.
5. Present the exact canonical URL, stable IDs, release ID, revision digests, lifecycle, and
   evidence state.

Use `GET /v1/search` when the user is looking for vendors rather than individual offers.

### Check eligibility

1. Read the offer first.
2. Inspect its recursive eligibility rule and collect only the facts named by its predicates.
   Encode every fact with the declared typed value shape; do not infer missing facts.
3. Call `POST /v1/eligibility/check` with `{ offer_id, facts }`, or use the eligibility result and
   unresolved criteria returned by the MCP search or comparison tool.
4. Preserve all three result states:
   - `eligible: true`: the recursive trace evaluates to `met`.
   - `eligible: false`: identify the trace branches that evaluate to `unmet`.
   - `eligible: null`: identify the trace branches that evaluate to `unknown`; request missing
     facts if useful.
5. State that the result is a contract evaluation, not vendor approval.

### Verify a claim

1. Read the entity or offer and capture its `revision_digest`.
2. Call `GET /v1/revisions/{id}/provenance` or pass one to ten exact Offer revision digests to the
   evidence tool advertised by MCP `tools/list`.
3. Follow referenced event and observation IDs with `/v1/events/{id}` and
   `/v1/observations/{id}`.
4. Distinguish independent trust facts:
   - `vendor_attestation.status: current`: current vendor authority attested to the exact revision.
   - Entity `identity_assurance.status: verified`: Sourcey checked the company name and primary
     domain for the current identity epoch.
   - Offer `terms_assurance.status: checked`: Sourcey checked this exact Offer revision.
   - provenance fields: admitted evidence coverage, freshness, disputes, and exact basis events.
5. Report stale, unknown, or disputed fields explicitly. Do not summarize them away.

### Follow changes

1. Call `GET /v1/changes` or the change-feed tool advertised by MCP `tools/list`.
2. Store `next_cursor` exactly as returned.
3. Pass it unchanged on the next call.
4. On `invalid_cursor`, discard it and restart from the retained boundary.
5. Use `https://api.sourcey.com/feed.json` for JSON Feed readers; use `/v1/changes` when exact
   cursor semantics matter.

### Read agent readiness profiles

1. List an entity's profiles with `GET /v1/entities/{entity}/agent-readiness-profiles`.
2. Read an exact profile with `GET /v1/agent-readiness-profiles/{id}`.
3. Preserve the profile's letter, its steps, lifecycle, revision, and evidence label.
4. Say that no profile is available when the release contains none. Never infer one from brand
   popularity or catalog presence.

### Read the reports

1. Read the State of Startup Credits or State of Agent Readiness report with
   `GET /v1/reports/{report}` (`startup-credits` or `agent-readiness`) or the report tool advertised
   by MCP `tools/list`.
2. Treat the report as one release's figures: its `release_id` names the release it was written
   from, which may be earlier than the live release. Never state its figures as the live release's.
3. Quote its prose as written. Each sentence cites the fact-sheet statements it rests on and was
   judged against them; the figures, the names they cite and the fact sheets are in the same
   document.
4. Cite a report with `GET /v1/reports/{report}/releases/{release_id}` or its page
   `https://sourcey.com/reports/{report}/at/{release}`, which stays readable after the report is
   written again.

Read a listed comparison's writing with `GET /v1/comparisons/{entity}/{other_entity}`. A comparison
has a writing only while both companies' records and checks are as it was written from; otherwise
`writing` is null and the records themselves are the answer.

## HTTP surface

Use these public version-one operations:

- Status and release: `GET /v1/status`, `GET /v1/release`
- Whole catalog: `GET /v1/catalog`
- Entities: `GET /v1/entities`, `GET /v1/entities/{entity}`,
  `GET /v1/entities/by-slug/{entity}`
- Programs: `GET /v1/programs/{id}`, `GET /v1/programs/{entity}/{program}`
- Offers: `GET /v1/offers/{id}`, `GET /v1/offers/{entity}/{offer}`
- Search: `GET /v1/search`, `GET /v1/search/offers`
- Eligibility: `POST /v1/eligibility/check`
- Provenance: `GET /v1/provenance/{id}`, `GET /v1/revisions/{id}/provenance`
- Immutable objects: `GET /v1/revisions/{id}`, `GET /v1/events/{id}`,
  `GET /v1/observations/{id}`
- Change stream: `GET /v1/changes`
- Agent readiness: `GET /v1/entities/{entity}/agent-readiness-profiles`,
  `GET /v1/agent-readiness-profiles/{id}`
- Reports: `GET /v1/reports/{report}`, `GET /v1/reports/{report}/releases/{release_id}`
- Report figures of the live release: `GET /v1/statistics/startup-credits-report`,
  `GET /v1/statistics/agent-readiness-report`
- Comparisons: `GET /v1/comparisons/{entity}/{other_entity}`

Send `Accept: application/json`. Anonymous reads are supported. If the operator supplies a Sourcey
access key, send it as `Authorization: Bearer <token>` for identity and quota only; never expose it
in logs or output.

Read `x-request-id`, `x-sourcey-release-id`, and `x-sourcey-artifact-sha256` from responses when
debugging or preserving evidence. Follow the OpenAPI document for schemas and declared errors.

## MCP surface

Connect over Streamable HTTP with any published protocol revision: `initialize` for `2025-11-25`
and earlier, or per-request `_meta` with `server/discover` for `2026-07-28`. Send one JSON-RPC
message per request. The hosted manifest lists every
revision the server serves in `mcpVersions`. Treat `tools/list` as the complete executable contract. Select tools from their owner-authored names, titles, descriptions, and input
schemas; do not rely on a copied list in this guide. The hosted manifest and live tool list must
expose the same tool definitions. Matching never ranks or turns an unknown into approval. Comparison returns
stacking as not evaluated because the Catalog does not carry pairwise stacking evidence. All tools
are read-only, idempotent, and closed-world. Do not invent write tools or call hosted account,
claim, provider, or maintainer routes through MCP.

## Response discipline

For a recommendation, return:

1. Vendor, Program, and Offer name.
2. Structured value and lifecycle.
3. Eligibility result with unknowns.
4. Evidence freshness, dispute state, vendor attestation, and any applicable identity or terms
   assurance.
5. Canonical Sourcey URL.
6. Release ID and revision digest when the result will be stored, cited, or acted on.

Prefer a small evidence-backed shortlist over a long unranked dump. Explain ranking criteria.
Separate registry facts from judgment.

Handle failures as follows:

- `400`: fix the request or restart an invalid cursor.
- `401` or `403`: continue anonymously when the operation permits it; otherwise request a key.
- `404`: report absence in the pinned release; do not infer permanent nonexistence.
- `429`: respect retry metadata and back off.
- `500` or `503`: preserve the request ID and retry safely.

Do not retry malformed requests, authorization failures, or unknown MCP tools unchanged.

## Minimal examples

Search:

```sh
curl -fsS \
  -H 'accept: application/json' \
  'https://api.sourcey.com/v1/search/offers?q=database&limit=20'
```

Check eligibility:

```sh
curl -fsS \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -X POST \
  --data '{"offer_id":"offer_example","facts":{"company.stage":{"type":"string","value":"seed"},"company.country_code":{"type":"string","value":"AU"}}}' \
  'https://api.sourcey.com/v1/eligibility/check'
```

Inspect changes:

```sh
curl -fsS \
  -H 'accept: application/json' \
  'https://api.sourcey.com/v1/changes'
```