Agent API

Use SuperPenguin's organization-scoped spend and account data programmatically through OAuth-authenticated REST resources.

The SuperPenguin Agent API is the REST interface behind the remote MCP server. Both interfaces use the same operation registry, schemas, OAuth grants, organization binding, and live authorization checks.

Use MCP when an AI agent can connect to a remote MCP server. Use the Agent API when you are building your own application, scheduled script with an interactive user grant, or client integration and want ordinary HTTP resources.

Current boundary

The Agent API currently supports user-delegated OAuth access. It does not accept SuperPenguin SDK ingestion keys, provider credentials, arbitrary Supabase tokens, or static bearer tokens. It does not yet support OAuth client credentials or unattended service accounts.

A human must complete OAuth in a browser, choose a SuperPenguin organization, review scopes, and approve the connection. The resulting grant stays bound to that user, OAuth client, and organization. Every request rechecks current membership, role, plan, scopes, and resource availability.

Base URLs

REST base: https://app.superpenguin.ai/api/agent/v1
OAuth resource: https://app.superpenguin.ai/api/mcp
Protected-resource metadata: https://app.superpenguin.ai/.well-known/oauth-protected-resource/api/mcp
Authorization-server metadata: https://app.superpenguin.ai/.well-known/oauth-authorization-server/api/agent/oauth
Authenticated OpenAPI 3.1: https://app.superpenguin.ai/api/agent/v1/openapi

The OpenAPI document is generated from the live operation registry and includes only operations visible to the current OAuth grant. Fetch it with the same bearer token used for REST requests; an unauthenticated browser request correctly returns 401.

OAuth

Use a maintained OAuth client library instead of constructing authorization URLs by hand. The discovery metadata advertises dynamic client registration, authorization-code and refresh-token grants, PKCE S256, offline_access, and the supported read scopes.

Register a public client with an HTTPS or loopback redirect URI, then authorize against the discovered issuer using the resource https://app.superpenguin.ai/api/mcp. Request only the scopes your client needs. Store access and refresh tokens in a secure credential store and never commit, log, or paste them into an AI conversation.

Access tokens expire after 15 minutes. Use the issued refresh token rather than asking the user to sign in for every request. A user can revoke the grant from Agent connections.

Start with context and discovery

Before calling domain resources, confirm the bound workspace and available workflows:

GET /api/agent/v1/context
Authorization: Bearer <access-token>

Discover a small relevant set of operations and their schemas:

GET /api/agent/v1/capabilities?q=weekly%20spend
Authorization: Bearer <access-token>

You can inspect one exact operation at /api/agent/v1/capabilities/{operationId} or one guided workflow at /api/agent/v1/workflows/{workflowId}. Do not hardcode operation inputs from examples when the authenticated OpenAPI or capability response can supply the current schema.

Domain resources

The scope-filtered OpenAPI document is authoritative. Currently published resource families include:

SDK and OpenTelemetry usage summaries and breakdowns over named or exact time windows
Provider billing summaries and breakdowns for explicit invoice and reconciliation questions
Durable analytics SQL schema, submission, status, result paging, and cancellation
Aggregate Cursor, Claude Code, and Codex usage, plus session drill-down with separately labeled spend bases
Organization members and supported access diagnostics
Provider connections and safe health metadata
SuperPenguin SDK API-key metadata and health without secret values
Published optimizations and evidence-backed recommended actions

Most read resources use GET with strict scalar query parameters. Analytics submission and cancellation use JSON POST requests. Unknown, repeated, or incorrectly typed parameters are rejected rather than silently ignored.

For example, after OAuth grants spend:read:

curl --fail-with-body \
  --header "Authorization: Bearer $SUPERPENGUIN_AGENT_TOKEN" \
  "https://app.superpenguin.ai/api/agent/v1/usage/summary?window=last_7_days&timezone=UTC&compare=true"

This returns one direct spendUsd value, its exact amountMicros, resolved window, usage metrics, freshness, and an optional preceding-period comparison. Use /usage/breakdown?groupBy=workflow to rank common spend drivers. Exact custom windows use inclusive start and exclusive end timestamps and may span at most 90 days.

Ordinary spend, cost, and usage requests refer to SDK and OpenTelemetry-observed usage. If the user explicitly wants provider billing or invoice reconciliation, use /billing/summary or /billing/breakdown; these UTC calendar reads are intentionally separate.

For AI coding, /coding/usage-summary?tool=cursor&scope=self&window=this_week returns the total and top contributors in one call. Use session listing and session spend only to inspect one explicitly selected session, never to reconstruct an aggregate.

Treat unavailable or incomplete cost as unknown rather than zero.

Responses, errors, and retries

Domain results use a versioned envelope containing schemaVersion, requestId, and data. Responses include Cache-Control: no-store and X-Request-Id; retain the request ID when reporting a problem.

Errors return a safe JSON body with error.code, error.message, error.retryable, and the request ID. A 401 means the client must connect or reconnect. A 403 can include the missing scope and does not mean broader OAuth consent will override the user's product role. A 429 or pending analytics response includes retry guidance that the client must honor.

Analytics submission returns 201 when it finishes inline or 202 with Location and Retry-After when it is still queued or running. Submit SQL once with an idempotency key, then follow the returned query URL using the same handle. Never resubmit SQL merely to poll.

Which API key is which?

SuperPenguin SDK API keys send usage telemetry into SuperPenguin. They are not credentials for reading organization data. The Agent API reads organization data through a user-approved OAuth grant so the caller inherits the user's live role and cannot silently cross workspaces.