Management API

Everything the console does, it does through the management API, and a gateway key with the right scopes can do the same.

Base URL and authentication

Deployment	Base URL
Hosted	https://acog.tessarac.com/api
Self-hosted	https://<your-acog-host>/api

Authenticate with a gateway key whose scopes include the permission each endpoint needs:

curl -s https://acog.tessarac.com/api/v1/orgs/$ORG_ID/providers \
  -H "Authorization: Bearer $ACOG_ADMIN_KEY"

x-acog-key works too. A key’s scopes are permissions (see Roles and permissions); a key can never hold more than the person who created it, and seeing the Activity page’s conversations (audit:conversations) is never available to a key.

Your organization ID (org_…) is on Admin → Organization. Routes under /v1/orgs/{org} act only on your own organization: another organization’s ID answers 404, as if it did not exist.

Requests and responses are JSON. Creating returns the created object; deleting returns 204 No Content. Errors use standard status codes: 400 for an invalid body, 401 without a valid principal, 403 without the permission (the message names the permission), 404 for not found, 409 for a conflict.

Endpoints

Provider connections

Method	Path	Permission
GET	/v1/orgs/{org}/providers	admin:providers
POST	/v1/orgs/{org}/providers	admin:providers
DELETE	/v1/orgs/{org}/providers/{id}	admin:providers
GET	/v1/orgs/{org}/providers/bedrock-external-id	admin:providers
GET	/v1/orgs/{org}/providers/workload-identity	admin:providers
GET	/v1/orgs/{org}/channels	proxy

A connection is created with:

{
  "channel": "vertex",
  "provider": "gemini",
  "display_name": "Vertex Gemini",
  "public": {
    "project_id": "my-project",
    "region": "us-central1",
    "auth_mode": "workload_identity",
    "workload_identity_provider": "projects/123456789/locations/global/workloadIdentityPools/acog/providers/acog-gateway",
    "models": ["gemini-3.5-flash", "gemini-3.1-flash-lite"],
    "default_model": "gemini-3.5-flash"
  },
  "secret": {}
}

public is stored and readable; secret is encrypted, write-only and never returned. Each provider page lists its fields. Posting a channel and family that already has a connection replaces it. GET …/providers/workload-identity returns your organization’s issuer URL, subject and key set for keyless connections.

API keys and Bedrock credentials

Method	Path	Permission
GET	/v1/orgs/{org}/api-keys	any principal (your own keys; all keys with admin:keys)
POST	/v1/orgs/{org}/api-keys	any principal
DELETE	/v1/orgs/{org}/api-keys/{id}	any principal (your own keys; any key with admin:keys)
GET, POST	/v1/orgs/{org}/bedrock-credentials	admin:keys
DELETE	/v1/orgs/{org}/bedrock-credentials/{id}	admin:keys

curl -s -X POST https://acog.tessarac.com/api/v1/orgs/$ORG_ID/api-keys \
  -H "Authorization: Bearer $ACOG_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "billing-service", "scopes": ["proxy"], "allowed_cidrs": ["203.0.113.0/24"]}'

The response’s key field is the only time the key is shown. DELETE disables an active key; DELETE …/api-keys/{id}?purge=true then removes the disabled key permanently. See API keys.

Users, roles and invitations

Method	Path	Permission
GET	/v1/orgs/{org}/users	read:metrics
PUT, DELETE	/v1/orgs/{org}/users/{id}	admin:users
GET, POST	/v1/orgs/{org}/roles	admin:users
PUT, DELETE	/v1/orgs/{org}/roles/{id}	admin:users
GET, POST	/v1/orgs/{org}/invites	admin:users (hosted)
DELETE	/v1/orgs/{org}/invites/{id}	admin:users (hosted)
POST	/v1/orgs/{org}/users	admin:users (self-hosted: returns a one-time initial password)

Budgets

Method	Path	Permission
GET	/v1/orgs/{org}/budgets	read:billing
PUT	/v1/orgs/{org}/budgets/{scope}/{entityID}	admin:budgets
DELETE	/v1/orgs/{org}/budgets/{scope}/{entityID}	admin:budgets
GET	/v1/budgets/usage	read:billing

curl -s -X PUT https://acog.tessarac.com/api/v1/orgs/$ORG_ID/budgets/org/$ORG_ID \
  -H "Authorization: Bearer $ACOG_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": 5000, "window": "month"}'

scope is org, group (a team) or user, and entityID is the organization, team or user ID. See Budgets.

Webhooks

Method	Path	Permission
GET	/v1/webhook-events	any principal
GET, POST	/v1/orgs/{org}/webhooks	admin:org
PUT, DELETE	/v1/orgs/{org}/webhooks/{id}	admin:org
POST	/v1/orgs/{org}/webhooks/{id}/rotate-secret	admin:org
POST	/v1/orgs/{org}/webhooks/{id}/ping	admin:org
GET	/v1/orgs/{org}/webhooks/{id}/deliveries	admin:org

See Webhooks for events, payloads and signature verification.

Usage and savings

Method	Path	Permission
GET	/v1/orgs/{org}/dashboard/summary?window=30d	read:metrics
GET	/v1/orgs/{org}/dashboard/timeseries?window=30d&bucket=day	read:metrics
GET	/v1/orgs/{org}/dashboard/breakdown?dimension=model&window=30d	read:metrics

Field	Meaning
request_count	Requests in the window
spent_usd	What the traffic cost through ACOG
would_have_spent_usd	The same traffic at your providers’ list prices with no optimization
saved_usd	The sum of each request’s saving
gainshare_usd, net_saved_usd	The share billed on the saving (hosted), and the saving after it
savings_pct	The saving as a share of would_have_spent_usd
by_disposition	Requests and saving per disposition

breakdown takes dimension = model, channel, endpoint, key_id or user.

Billing (read only)

Method	Path	Permission
GET	/v1/orgs/{org}/billing	read:billing
GET	/v1/orgs/{org}/billing/invoices	read:billing

Organization and settings

Method	Path	Permission
GET	/v1/orgs/{org}	read:metrics
PUT	/v1/orgs/{org}	admin:org
GET, PUT	/v1/orgs/{org}/settings	admin:org

Licence (self-hosted)

Method	Path	Permission
GET	/v1/license	read:billing
POST	/v1/license/load	admin:org
DELETE	/v1/license	admin:org
GET	/v1/license/usage-export	admin:org

See Licensing.