---
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; 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 registry. 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`
- 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.

## 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 `provenance.tier`, `freshness`, `dispute`, and `lifecycle` 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:
   - `signed`: a current authorized party attested to the revision.
   - `verified`: independent verification satisfies the release policy.
   - `observed`: the release contains bounded source observations without stronger authority.
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 basis, grade, lifecycle, revision, and evidence state.
4. Say that no profile is available when the release contains none. Never infer one from brand
   popularity or catalog presence.

## 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}`

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

Initialize with a supported `MCP-Protocol-Version`, then 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. Provenance tier, freshness, and dispute state.
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'
```