API reference

REST docs for scoped creative-pack keys.

Connect a server integration with scoped keys, the Swagger-compatible OpenAPI schema, and the paid creative-pack request loop.

Open schema JSON Run quickstart

Runtime contract

Originhttps://formatry.cc

OpenAPI/api/v1/openapi.json

Version2026-06-18

AuthAuthorization: Bearer <api-key> or X-API-Key: <api-key>

Designer handoff

CreateCreate a scoped server key from account access or with an existing management key.

StoreKeep the secret in a password manager or server secret store; never commit it or paste it into client code.

LimitGive the designer only the scopes needed for balance, uploads, jobs, artifacts, and usage checks.

RotateRevoke and create a new key when the integration owner changes.

Open account keys

Swagger and REST

Import the schema, then test with a balance request.

Swagger/OpenAPI URL
https://formatry.cc/api/v1/openapi.json

Import this URL into Swagger UI, Postman, Insomnia, or OpenAPI codegen.
FORMATRY_CC_ORIGIN=https://formatry.cc
FORMATRY_CC_API_KEY=<secret key shown once on creation>

curl "$FORMATRY_CC_ORIGIN/api/v1/balance" \
  -H "Authorization: Bearer $FORMATRY_CC_API_KEY"

Endpoints

REST surface covered by the current OpenAPI schema.

POST/api/v1/codex/trial-key

Claim a temporary Codex plugin trial key.

Schema
GET/api/v1/balance

Read the workspace credit balance for the API key.

Scoped key
GET/api/v1/usage

List recent workspace usage ledger events.

Scoped key
GET/api/v1/api-keys

List workspace API keys without exposing secrets.

Scoped key
POST/api/v1/api-keys

Create a workspace API key and return its secret once.

Scoped key
DELETE/api/v1/api-keys/{apiKeyId}

Revoke one workspace API key.

Scoped key
GET/api/v1/assets

List workspace assets visible to new generation jobs.

Scoped key
GET/api/v1/assets/{assetId}

Read one workspace asset by id.

Scoped key
DELETE/api/v1/assets/{assetId}

Soft-delete one workspace asset.

Scoped key
POST/api/v1/assets/uploads

Create an upload intent for a workspace asset.

Scoped key
POST/api/v1/assets/uploads/{uploadId}/complete

Verify a previously uploaded object and mark the asset ready.

Scoped key
PUT/api/v1/assets/uploads/{uploadId}/object

Upload bytes for a pending workspace asset.

Scoped key
PUT/api/v1/assets/upload-object

Upload bytes through the proxy URL returned by an upload intent.

Scoped key
GET/api/v1/previews/quota

Read the effective protected-preview allowance and policy.

Scoped key
POST/api/v1/previews

Create one bounded protected PNG preview.

Scoped key
GET/api/v1/jobs

List workspace-owned generation jobs.

Scoped key
POST/api/v1/jobs

Create a paid pack request and reserve workspace balance once.

Scoped key
GET/api/v1/jobs/{jobId}

Read workspace-owned generation job status.

Scoped key
POST/api/v1/jobs/{jobId}/cancel

Cancel a queued generation job and release reserved balance.

Scoped key
GET/api/v1/artifacts/{artifactId}

Read the artifact family for a workspace-owned generation job.

Scoped key
GET/api/v1/artifacts/{artifactId}/download

Get short-lived signed artifact download information.

Scoped key
GET/api/v1/artifacts/{artifactId}/files/{fileId}/download

Download one ready artifact file through scoped API authentication.

Scoped key