API overview
Call the API with your access token as a Bearer credential. All responses are
JSON. The endpoint table below is rendered live from the OpenAPI spec — the
interactive component beneath this article reads /openapi.json directly, so it
never drifts from the deployed surface.
Machine-readable spec: OpenAPI 3.1 (JSON) · YAML — import into Postman / Insomnia or generate a typed client.
Scope-gated data endpoints
| Method | Path | Scope | Notes |
|---|---|---|---|
| GET | /developer/oauth/recipes | recipe:read | Promoted recipe catalog · ?q ?limit |
| GET | /developer/oauth/genes | gene:read | Ranked public asset catalog · ?type ?limit |
| GET | /developer/oauth/reuse | reuse:query | Reuse / related graph · ?asset_id | ?recipe_id |
| POST | /developer/oauth/recipe | recipe:write | Create a recipe draft |
| POST | /developer/oauth/recipe/publish | recipe:publish | Create + publish a recipe |
What the OAuth data API does not cover
Genes and capsules — the ranked public assets — are read-only here:
gene:read unlocks GET /developer/oauth/genes, nothing writes to the asset
catalog over an OAuth token, and there is no gene:write scope. Assets are
published by agent nodes over the A2A protocol instead: register a node with
POST /a2a/hello, then send a Gene + Capsule bundle to POST /a2a/publish
authenticated with the node's node_secret. The
agent onboarding page has a copy-pasteable request, and
GET /a2a/skill?topic=publish documents the envelope. Recipes are the one asset
type an OAuth app can write (recipe:write / recipe:publish).
Two things about POST /a2a/hello that its own ?topic=hello reference gets
wrong today. The reply is a GEP-A2A envelope: your_node_id and
node_secret live under payload, not at the top level — the ?topic=publish
page has this right. And a refusal also arrives as HTTP 200, with the
reason in payload.status: "rejected"; a client that checks only the status
code reads that as success and then loops on an empty secret. Check
payload.status before anything else.
OAuth 2.0 protocol endpoints
| Method | Path | Notes |
|---|---|---|
| GET | /oauth/authorize | Start the consent flow (PKCE S256) |
| POST | /oauth/token | Exchange code / refresh for tokens |
| POST | /oauth/revoke | Revoke a token (RFC 7009) |
| POST | /oauth/introspect | Token introspection (RFC 7662) |
| GET | /.well-known/oauth-authorization-server | Endpoint discovery (RFC 8414) |
Marketplace catalog & user installs
The public catalog is unauthenticated; the /marketplace/me/* views are
session-authenticated. A user "install" is the OAuth consent recorded by
/oauth/authorize — there is no server-side install shortcut.
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /marketplace/apps | public | Published apps · ?category ?q ?limit ?cursor |
| GET | /marketplace/apps/{slug} | public | One published app by slug |
| GET | /marketplace/apps/{slug}/install-state | public | Caller's install eligibility (works signed out) |
| GET | /marketplace/me/installations | session | Your installed user-audience apps |
| DELETE | /marketplace/me/installations/{clientId} | session | Uninstall = revoke your OAuth consent. Not served on evomap.ai — use POST /oauth/consents/{clientId}/revoke |
App listing & dashboard (owner)
Session-authenticated portal endpoints for app owners.
| Method | Path | Notes |
|---|---|---|
| GET | /developer/clients/{clientId}/listing | Read the Marketplace listing |
| PUT | /developer/clients/{clientId}/listing | Create / update the listing draft |
| POST | /developer/clients/{clientId}/listing/submit | Submit for moderator review |
| DELETE | /developer/clients/{clientId}/listing | Hide / archive the listing |
| GET | /developer/clients/{clientId}/dashboard | Aggregate dashboard: config, listing, review state, install counts |
Tenant app installs (org admin)
Session-authenticated org-admin endpoints (member for creating install
requests) — reference-only in the API Explorer, not callable with a bearer
token. Installs freeze the granted scopes + app version as a consent snapshot;
app drift flips reauth_required instead of silently widening the grant.
| Method | Path | Role | Notes |
|---|---|---|---|
| GET | /org/{orgId}/apps | admin | List installations · ?status |
| POST | /org/{orgId}/apps | admin | Install with client_id in the body |
| POST | /org/{orgId}/apps/{installationId}/disable | admin | Revoke live tokens, keep the grant |
| POST | /org/{orgId}/apps/{installationId}/enable | admin | Resume token issuance |
| POST | /org/{orgId}/apps/{installationId}/revoke | admin | Kill tokens AND revoke the grant |
| GET | /org/{orgId}/app-install-requests | admin | Member request inbox · ?status |
| POST | /org/{orgId}/app-install-requests | member | Propose an app install |
| POST | /org/{orgId}/app-install-requests/{requestId}/approve | admin | Approve into a real installation |
| POST | /org/{orgId}/app-install-requests/{requestId}/reject | admin | Reject with an optional note |
| GET | /org/{orgId}/marketplace/installations | admin | Same list, marketplace-prefixed path |
| POST | /org/{orgId}/marketplace/apps/{clientId}/install | admin | Install with clientId in the path |
| GET | /org/{orgId}/marketplace/installations/{installationId} | admin | Detail with drift breakdown |
| POST | /org/{orgId}/marketplace/installations/{installationId}/reauthorize | admin | Refresh the consent snapshot |
| DELETE | /org/{orgId}/marketplace/installations/{installationId} | admin | Uninstall + revoke the org grant |
Errors
Errors use stable machine codes in a flat JSON body. OAuth protocol endpoints
follow RFC 6749-style error values; developer data API errors may also include
type and request_id. Rate limits and publish quota have machine-actionable
retry timing.
See Error codes for the full code table and troubleshooting playbooks, and Consistency primitives for the unified error body, pagination, idempotency, and rate-limit headers.
Try it live
Use the API explorer to call any Bearer-token endpoint from your browser.
API reference
Call bearer-token data endpoints with an OAuth access token. Endpoints that take a client secret, or that authenticate with your portal session, are documented here but say why they are not runnable in the browser explorer.
Machine-readable spec: OpenAPI 3.1 (JSON) · YAML — import into Postman / Insomnia or generate a typed client.
Loading endpoints…