Overview and conventions

The HTTP APIs are InBlack’s product service layer. Product UIs call them directly. Agents may use them for ADR-0019 carve-outs, but MCP remains the default agent API.

Service map

Service	Public routes
portal-api	`https://api.portal.inblack.app`; GraphQL and `/api/...`
accounting-api	`https://api.inblack.app`; GraphQL and selected `/api/...` routes
commerce-api	`https://api.commerce.inblack.app`; GraphQL, product, storefront, and agentic routes
customer360-api	`https://cx-api.inblack.app`; GraphQL
studio-api	`https://api.studio.inblack.app`; GraphQL and GitHub callback
reporting-api	`https://api.reporting.inblack.app/api/v1/reporting/...`

Agent/API boundary

Use APIs directly for:

Product UI requests.
Backend integrations.
Read-heavy queries.
Bulk operations.
Streaming or protocol-specific routes.
Storefront SDK traffic.
Signed agentic commerce traffic.
Code-mode orchestration.
Internal admin endpoints.

Use MCP for:

Agent actions that benefit from typed tools, simulate previews, pending actions, and catalog visibility.
Customer-facing writes that mutate financial state, including inside code-mode.

Auth and tenant context

Most product routes are wrapped in bearer auth and tenant resolution. Public GraphQL handlers in the pillar APIs are mounted at /graphql; the exact middleware varies by service. Portal also exposes REST routes such as billing and external-agent signup under /api/....

Send:

Authorization: Bearer <token>
X-Tenant-ID: <tenant-id>
Content-Type: application/json

Use X-Tenant-ID when the token or route does not otherwise resolve tenant context. Internal routes use service-token style middleware and are not external customer integration surfaces.

GraphQL vs REST

Pattern	Used for
GraphQL `/graphql`	Portal, Accounting, Commerce admin, Customer 360, Studio
REST `/api/...`	Portal billing/signup, commerce imports, webhooks, reporting resources
REST `/storefront/v1/...`	Commerce storefront SDK and customer-facing storefront routes
REST/MCP protocol `/agentic/...`	Signed commerce shopping-agent protocols

Code-mode

Code-mode can call APIs directly when that is the efficient unit of work. The security model comes from ADR-0020: scoped capabilities, sandboxing, review for write-heavy invocations, and rate/volume controls.

The exception does not cover customer-facing financial writes. If code-mode needs to post a journal entry, issue a refund, adjust an account, or mutate the books, call MCP from inside the code.

Idempotency

Use idempotency keys for writes when the target service supports them. MCP write tools add idempotency_key to write schemas when missing. API idempotency support is service-specific, so cite the resolver or handler before publishing a page that promises replay behavior.

Errors

GraphQL routes return GraphQL errors. REST and MCP-adjacent routes return service-specific JSON error envelopes. MCP tool calls use INBLACK_* error codes from the Worker catalog.