Guides

Use the API

Call SUMR from trusted backend services, CI jobs, and automation using HTTPS and a secret API key.

Base URL

Production starts at /v3.

Use the production host for live integrations. SUMR will provide separate hosts for development or staging environments when needed.

terminal

$curl https://api.sumr.co/v3/playbook/catalogs -H "x-api-key: sumr_sk_live_<keyId>_<secret>"# call with a secret API key

Authentication

Keep keys server-side.

Send secret keys in the x-api-key header from backend code only. Never expose secret keys in browser JavaScript, mobile apps, public repositories, logs, or screenshots.

terminal

$export SUMR_API_KEY="sumr_sk_live_<keyId>_<secret>"# load from your secret store$curl https://api.sumr.co/v3/playbook/catalogs -H "x-api-key: $SUMR_API_KEY"# make the request

Read API keys for key generation, storage, rotation, revocation, and scope guidance.

Create a key

Choose one account and the smallest useful scopes.

The generated secret is shown once. Copy it immediately and store it in your secrets manager.

terminal

$curl https://api.sumr.co/v3/identity/api-keys -H "Authorization: Bearer <user-access-token>" -H "Content-Type: application/json" -d '{"name":"Production backend","accountId":"<account-id>","scopes":["playbook:read","playbook:write"]}'# create a scoped API key

Errors

Handle responses deliberately.

200 / 201

Request succeeded.

400

The request body or parameters are invalid.

401

The access token or API key is missing, invalid, expired, or revoked.

403

The key is valid but does not have access to that account, scope, or resource.

404

The requested resource does not exist or is not visible to the key.

429

Too many requests. Retry with backoff.

5xx

SUMR could not complete the request. Retry idempotent operations safely.