# Cormak.app — Official API

Use the existing OAuth integration gateway at **https://mcp.cormak.app**.
The Store API generates product descriptions and images. The MCP server exposes
scoped tasks, projects, agents and creative workflows. This package documents
implemented interfaces; it does not introduce a general REST `/v1` service.

## Getting started: your first HTTP 200

No account, token, write or credits are required for discovery:

```sh
curl --fail https://mcp.cormak.app/.well-known/oauth-protected-resource/mcp
```

The response contains `resource: "https://mcp.cormak.app/mcp"`, authorization
servers and supported scopes. Import `Cormak.postman_collection.json` and
`Cormak.postman_environment.json`, select the environment, and send
**01 Discovery → 1. OAuth resource metadata**. Run the whole discovery folder
for two metadata checks and two expected-401 checks.

## Authentication and API keys

Cormak.app uses an existing OAuth public-client flow with PKCE S256, opaque
bearer access tokens and rotating refresh tokens. Personal API keys are not
implemented. The required Postman variable **`apiKey` means your OAuth access
token**, without the `Bearer ` prefix. It is blank in this package.

1. Read `/.well-known/oauth-authorization-server/mcp` for the real endpoints.
2. Register a public client at `POST /mcp/register` with `client_name`,
   `redirect_uris`, and `token_endpoint_auth_method: "none"`. This creates a
   record: do it only as an intentional setup step. Register the callback
   actually used by your Postman OAuth helper. The template callback is
   `https://oauth.pstmn.io/v1/callback`; change both registration and helper if
   your Postman client shows a different callback.
3. Generate a fresh 43–128 character PKCE verifier locally and derive its
   base64url SHA-256 challenge. Example (prints local temporary PKCE material):

   ```sh
   node -e 'const c=require("node:crypto");const v=c.randomBytes(32).toString("base64url");console.log({verifier:v,challenge:c.createHash("sha256").update(v).digest("base64url")})'
   ```

4. Open `/mcp/authorize` in a browser with `response_type=code`, registered
   `client_id` and exact `redirect_uri`, `code_challenge_method=S256`, your
   challenge, unpredictable `state`, explicit minimum `scope`, and
   `resource=https://mcp.cormak.app/mcp`. Sign in to Cormak and review scopes
   and connection limits. Verify the returned `state` before accepting the code.
5. Exchange the code at `POST /mcp/token` with form encoding:
   `grant_type=authorization_code`, `client_id`, `redirect_uri`, `code`,
   `code_verifier`, and the same `resource`. No client secret.
6. Keep the token in a private local environment or Vault-backed local
   workflow; never put it in shared/initial values, examples, URLs or public
   exports. For this collection, set local `apiKey` to the access token.

Postman's OAuth helper can perform steps 3–5: **Authorization Code (With PKCE)**,
SHA-256, discovered authorize/token URLs, registered callback, no client secret,
client credentials in the request body. Include `resource` on authorization
and token requests. Setup requests in the collection are blocked until local
`allowOAuthSetup=true`; owner approval is required before executing them.
The collection never automatically stores token responses.

Access lasts at most 1 hour; the connection grant lasts up to 90 days. Serialize
refresh calls under a client lock and atomically replace access/refresh tokens.
Reusing an old refresh token revokes the connection. `POST /mcp/revoke` with
form `client_id`, `token` (and resource) revokes matching connection tokens;
HTTP 200 has an empty body even for an unknown token. The owner can revoke
connections, change generation limits and review operations at
[Manage connections](https://app.cormak.app/mcp).

Use `store:use` for `/store`. Use `account:read projects:read` for the MCP
read-only quickstart. Request the minimum rights explicitly: omitting scopes
uses broad MCP defaults. Scopes must exist in **both token and current grant**.
Store-only tokens expose no MCP tools.

## Store quickstart: an authenticated read

After granting `store:use`, send **02 Authorized reads → Account and current
prices**. Equivalent request (keep CORMAK_ACCESS_TOKEN private):

```sh
curl --fail https://mcp.cormak.app/store \
  -H "Authorization: Bearer $CORMAK_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"action":"account"}'
```

The response contains `api_version: 1`, `available_ai_credits`, `daily_limit`,
`used_today`, `prices` and connection expiry. The actual response also contains
your email; never publish captured account responses. Synthetic example:

```json
{"api_version":1,"email":null,"plan":"free","available_ai_credits":10,"can_pay_images":false,"ai_consent_required":false,"daily_limit":100,"used_today":0,"connection_expires_at":"2027-01-01T00:00:00Z","prices":{"currency":"ai_credits","text":1,"images":{"nano2":{"standard":2,"high":3}}},"links":{"billing":"https://app.cormak.app/billing","connections":"https://app.cormak.app/mcp","library":"https://app.cormak.app/photo","settings":"https://app.cormak.app/settings"}}
```

This example shows only one image model; use the complete live price map.
The API is intended for server-to-server/native integration. `/store` does not
implement browser CORS/preflight; MCP allows only its own and the Cormak app's
origin when an Origin header is present. Use the Postman desktop agent if a web
agent sends an unsupported Origin. Never remove these boundaries for a demo.

## API reference

| Method / path | Purpose | Writes / credits |
|---|---|---|
| GET `/.well-known/oauth-protected-resource/mcp` | Resource and scopes | None |
| GET `/.well-known/oauth-authorization-server/mcp` | OAuth endpoints and capabilities | None |
| POST `/mcp/register` | Register public OAuth client | Creates record; no credits |
| GET `/mcp/authorize` | Browser owner consent | Creates pending authorization; no credits |
| POST `/mcp/token` | Code exchange / serialized refresh | Issues or rotates tokens; no credits |
| POST `/mcp/revoke` | Revoke connection tokens | Invalidates access; no credits |
| POST `/store`, `action=account` | Own wallet, prices and limits | No credits |
| POST `/store`, `action=fill_text` | Factual product content | **1 AI credit** |
| POST `/store`, `action=image_start` | One product photo | **Current model/quality quote** |
| POST `/store`, `action=image_status` | Up to 8 unique UUIDs | Reconciles existing jobs; no new generation |
| POST `/mcp` | JSON-RPC handshake, tool discovery/calls | Per-tool scopes, writes and costs |

See **openapi.yaml** for complete inputs, schemas, examples and HTTP responses.
`MCP_REFERENCE.md` and `mcp-tools.json` contain source-derived tool inputs and
restrictions. `MCP.md` covers transport, result envelopes and polling.
There are no documented or implemented `/v1/sites`, `/v1/videos`, `/api/keys`
or generic proxy endpoints in this release.

## Store generation, costs and retries

The collection's paid folder is **blocked by default** with
`pm.execution.skipRequest()`. Only after explicit owner approval set local
`allowPaidRequests=true`. The examples do not auto-enable this flag, mint new
UUIDs, start generations or follow an approval link. Use a client supporting
`skipRequest`; validate the guard before running paid folders.

For text, pass a stable UUID `request_id`, `product.name` (at least 2 characters)
and selected `options.fields`. Text generation normally returns HTTP 200 with
`status=complete`, `credits_charged=1` and factual result fields. An in-flight
retry returns 202/running. A failed/unknown replay can return 200: inspect the
body, not just HTTP status. A failed text generation is refunded through the
existing charge ledger. Only allowed HTML tags survive normalization.

For photos, read current `account.prices`, select model/quality and pass exactly
matching `expected_credits` with `image_start`. It returns 202 and
`request_id`, `status`, `credits_max`. This includes terminal replays: poll
`image_status` using the same original request UUID. Each operation produces
one frame; `variation` chooses a composition, not an image count. Free trial
photos have separate account/email/model restrictions and still need the
normal quote. A completed photo returns a private signed URL lasting 3,600
seconds; refresh status to obtain another URL.

`running` can become `complete`, `failed` or `unknown`; a missing image request
is `not_found` within the status response. A stale running photo after five
minutes is reconciled to `unknown`. Do not automatically resubmit an unknown
outcome, change its UUID or assume a refund. Check the Cormak library/receipt.
On network loss or 502–504, retry the **identical body and UUID**, with bounded
backoff. Changed arguments with the same UUID give `idempotency_conflict`.

Store requests themselves authorize spending within the store generation
quota; the MCP product manual/delegated credit budget is a separate mechanism.
Do not assume a store request waits for an approval URL. Photos retain existing
AI consent, moderation, wallet, subscription and backend charging rules.

## Rate limits and errors

| Boundary | Existing limit |
|---|---|
| MCP | 120 requests/minute per grant; 429 with `Retry-After: 60` |
| Store | 120 requests/minute per grant; error body, **no guaranteed Retry-After** |
| OAuth registration | 60/address/hour; 1,000 global/hour |
| Other OAuth routes | 300/address/minute; 30,000 global/hour per route |
| Connection generations | Owner selects 0–10,000 in a rolling 24 hours; Store counts its own operations |
| JSON body | Store 6,500,000 bytes; MCP 13,000,000; OAuth 16,000 |

Paid modules additionally enforce their own rate, entitlement, wallet and abuse
checks. Back off on 429; do not route around grant limits with new clients.
Transport errors use `{"error":"code"}` (optional request_id, URL or charge
fields). OAuth uses its existing error codes; this release does not promise
one normalized cross-product error model.

| HTTP | Typical Store codes |
|---|---|
| 400 | `invalid_action`, `invalid_request`, `invalid_request_id`, `invalid_product_name`, `no_fields`, `prompt_required`, `unsafe_attachment` |
| 401 | `invalid_token`, `access_revoked` |
| 402 | `limit_reached`, `free_photo_model`, `photo_credits` |
| 403 | `insufficient_scope`, `account_unavailable`, `ai_consent_required`, `account_blocked`, `verify_email` |
| 409 | `idempotency_conflict`, `image_quote_changed` |
| 413 | `request_too_large` |
| 422 | `content_blocked`, `unsupported_claims` |
| 429 | `rate_limit_reached`, `generation_limit_reached`, `free_photo_paused` |
| 502 / 503 | `text_failed` / `store_unavailable`, `operation_unavailable` |

The `/store` Worker returns plain text 405 for non-POST methods. Avoid repeated
authentication failures; reconnect revoked/expired grants. MCP **HTTP 200 does
not establish tool success**; see MCP.md.

## Buying credits

Sign in to [Cormak.app Billing](https://app.cormak.app/billing#ai-credits) to buy AI-credit packs or choose a plan. API usage consumes the same account balance as Cormak.app. Video has separate credit packs. Current pack prices are shown in Billing; no payment credentials or checkout webhooks belong in an integration. After purchase, read account balance again before generation. Photos still follow account eligibility and model restrictions.

## Files and publication

- `Cormak.postman_collection.json`: safe discovery, Store reads, gated paid/setup requests.
- `Cormak.MCP.postman_collection.json`: HTTP JSON-RPC read-only MCP quickstart.
- `Cormak.postman_environment.json`: blank private credential template.
- `openapi.yaml`: OpenAPI 3.1 for existing integration routes.
- `MCP.md`, `MCP_REFERENCE.md`, `mcp-tools.json`: MCP transport and tool reference.
- `workspace-draft.json`: reviewed branding for a **private** draft workspace.

The package is prepared for review. A public workspace URL and Run in Postman
button are added only after the owner approves public visibility and the actual
published collection URL is verified. Public visibility exposes descriptions,
requests, schemas, scripts, variables and saved response examples. Keep all
credential values blank and never publish real responses. Verified Publisher
status is not claimed.

[Cormak.app](https://cormak.app) · [Application](https://app.cormak.app) ·
[Connections](https://app.cormak.app/mcp) · [Contact](https://cormak.app/contact)
