One origin, one namespace

Read credit balance and card availability

Returns the caller's credit balance and whether a card is on file. No card details are returned.

curl 'https://api.agentsky.dev/v1/billing' \
  -H "Authorization: Bearer ast_..."

Start saving a payment card

Returns a hosted card form URL to open in a browser. Saving the card does not charge it; auto top-up can charge it when a later session starts below the configured threshold. No request body is required.

curl -X POST https://api.agentsky.dev/v1/billing/card-setup \
  -H "Authorization: Bearer ast_..."

Read auto top-up settings

Whether the caller's saved card is charged when their balance falls under threshold_usd, and for how much credit. opted_out is true once the person turned it off, so a later top-up does not turn it back on. failure is the last charge that did not go through while it is on; paused when repeated failures stopped it.

curl 'https://api.agentsky.dev/v1/billing/auto-topup' \
  -H "Authorization: Bearer ast_..."

Change auto top-up settings

Omitted fields keep their value. threshold_usd is 5, 10 or 20; amount_usd is 10, 20, 50 or 100. Turning it on needs a saved card (402 no_payment_method — add one with POST /billing/card-setup) and agrees to the card processing fee each charge adds; turning it off is remembered. A workspace key or a restricted credential cannot change it.

curl -X PATCH https://api.agentsky.dev/v1/billing/auto-topup \
  -H "Authorization: Bearer ast_..."

Buy credit for your own balance with your saved card

Charges the caller's saved card the credit plus the card processing fee and adds the credit to their balance. amount is 1000, 2000, 5000 or 10000 cents. request_id makes a repeat of the same request charge once (200 instead of 201). Auto top-up is not changed. 409 card_required without a saved card (POST /billing/card-setup adds one), 402 card_declined, 503 payments_unavailable where card payments are not set up. A workspace key or a restricted credential cannot buy credit.

curl -X POST https://api.agentsky.dev/v1/billing/topups \
  -H "Authorization: Bearer ast_..."

Claim a credit invite link for your own balance

Redeems an operator's credit invite link (agentsky.dev/i/<code>) the way the invite page's Claim button does; code is the <code> part of the link. Not a workspace invitation: those are POST /invites/{token}. 201 granted, or 200 already_claimed when this account redeemed the link before (nothing is funded twice). 404 not_found for an unknown code; 410 invite_expired, invite_disabled or invite_used; 403 invite_not_yours for a personal link issued to another address, 403 account_ineligible for an unverified or banned account. Rate-limited per account (429 rate_limited with Retry-After). A workspace key or a restricted credential cannot claim credit.

curl -X POST https://api.agentsky.dev/v1/billing/credit-invites/claim \
  -H "Authorization: Bearer ast_..."

Account-wide usage across sessions and API keys

What the caller spent over a range of UTC days, from both lanes that debit their balance: their sessions (model, capability, connector and runtime calls) and their developer API keys. totals.bySource splits the totals by lane; groups break them down by group_by. A group's key is null where the dimension does not apply to its lane, so the groups always sum to the totals. Per-session detail is GET /sessions/{id}/usage.

curl 'https://api.agentsky.dev/v1/billing/usage' \
  -H "Authorization: Bearer ast_..."

Download every usage record in a range as CSV or JSONL

One row per session call and one per API key, UTC day and kind, streamed. Columns: source, at, sessionId, sessionName, apiKeyId, apiKeyName, kind, model, provider, tool, calls, inputTokens, outputTokens, cachedInputTokens, cacheCreationTokens, listCostUsd, billedCostUsd, coveredBy (subscription when a connected plan paid), requestId. The same file Billing's export downloads.

curl 'https://api.agentsky.dev/v1/billing/usage/export' \
  -H "Authorization: Bearer ast_..."

Per-request history of your developer API keys

One row per API gateway request the caller's developer API keys made in a range of UTC days, newest first, a page at a time: model, endpoint, tokens, list and billed cost, HTTP status and latency. Pass nextCursor back as cursor for the next page; it is null on the last page. Session usage is not included (source=session returns no rows). The same rows as Settings › API usage. 503 unavailable when the request log cannot be read; retry.

curl 'https://api.agentsky.dev/v1/billing/usage/requests' \
  -H "Authorization: Bearer ast_..."

Read your coding plan

Whether a paid month of the coding plan covers now (every API gateway call is then billed at cost), its monthly credit, when the month ends, whether it renews, why the last charge failed, and whether new members can join (enrollment open, full or closed).

curl 'https://api.agentsky.dev/v1/billing/coding-plan' \
  -H "Authorization: Bearer ast_..."

Join the coding plan, or change your monthly amount

Joining charges the caller's saved card amount_usd plus the card processing fee and adds amount_usd as purchased credit; the plan renews monthly on the same card. A current member's call changes the amount from the next renewal, charges nothing, and undoes a pending cancellation. request_id makes a repeat of the same join charge once. 409 card_required without a saved card (POST /billing/card-setup adds one), 402 card_declined, 403 enrollment_closed, 409 enrollment_full, 409 charge_in_progress, 503 payments_unavailable. A workspace key or a restricted credential cannot change the plan.

curl -X POST https://api.agentsky.dev/v1/billing/coding-plan \
  -H "Authorization: Bearer ast_..."

Stop your coding plan renewing

The plan does not charge again; the paid month and its credit stay. Join again with POST to undo it. A workspace key or a restricted credential cannot change the plan.

curl -X DELETE https://api.agentsky.dev/v1/billing/coding-plan \
  -H "Authorization: Bearer ast_..."

Your customer discount links and what they earned

For an account on an eligible platform discount plan: the plan links are priced from (source_plan.multiplier is the lowest share of public price a customer can be given), the active SKUs with your own price for each, every link you created with its customer price, redemptions and status, and your earnings per referred customer. 403 not_eligible for any other account.

curl 'https://api.agentsky.dev/v1/billing/referral-links' \
  -H "Authorization: Bearer ast_..."

Create a customer discount link

Pass exactly one of customer_multiplier (one share of public price for every model, 0.01 to 100) or sku_prices (a multiplier, or for SECOND-only SKUs an exact second_usd_per_unit, per SKU). No price may be below your own (400 below_floor). With audience_email the link is emailed to that customer and redeems once; email_status says whether the email was sent. max_redemptions defaults to 100 and expires_in_days to 30. 403 not_eligible without an eligible discount plan, 429 rate_limited after 20 emailed links in an hour, 503 unavailable while referral pricing is paused. A workspace key or a restricted credential cannot create links.

curl -X POST https://api.agentsky.dev/v1/billing/referral-links \
  -H "Authorization: Bearer ast_..."

Disable one of your customer discount links

The link can no longer be redeemed; customers already enrolled keep their price. 404 not_found when the link is not yours or is already disabled.

curl -X POST https://api.agentsky.dev/v1/billing/referral-links/sess_cmtb7q2j/disable \
  -H "Authorization: Bearer ast_..."

List live and recent credit campaigns

curl 'https://api.agentsky.dev/v1/credit-campaigns' \
  -H "Authorization: Bearer ast_..."

Issue a public credit link or personal email invitations

Only allowlisted administrators can use these operations. Use one UUID requestId per campaign and reuse the identical body after timeouts. Personal emails are deduplicated and each gets a distinct, email-bound single-use code. Existing verified, unbanned recipients are credited immediately. sendEmail explicitly authorizes product email. Code creation is atomic; delivery/credit failures are per recipient. Retry the same request for retry_needed credit results; never change requestId just to retry. Email status sent means SES accepted, not inbox delivery. Sending/uncertain attempts are not automatically resent; use the returned personal link for manual delivery. Responses contain bearer codes: keep private. A different body with the same requestId returns 409.

curl -X POST https://api.agentsky.dev/v1/credit-campaigns \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"requestId":"40a9ae2a-4ea5-4a50-987e-d8b3c99c96f0","amountUsd":20,"expiresInDays":30,"note":"Launch invitations","audience":{"kind":"recipients","emails":["recipient@example.com"]},"sendEmail":true}'

Read claim, email and recipient usage results

Returns grantedUsd, claimed, activeRecipients, agentUsageUsd and individual link states. Usage is agent/runtime ledger spend since first claim, excludes API gateway and is not attribution to the gifted credit pool.

curl 'https://api.agentsky.dev/v1/credit-campaigns/sess_cmtb7q2j' \
  -H "Authorization: Bearer ast_..."

Disable all unclaimed campaign codes

Already granted credit stays in recipients' accounts.

curl -X DELETE https://api.agentsky.dev/v1/credit-campaigns/sess_cmtb7q2j \
  -H "Authorization: Bearer ast_..."

What a session loads from the workspace's files

The workspace's context store, the files every session the caller starts loads (AGENTS.md, MEMORY.md, people/INDEX.md, projects/INDEX.md and the caller's own members/<handle>.md) with their sizes and limits, and the folders read on demand. What one session actually loaded is its `contextFiles`.

curl 'https://api.agentsky.dev/v1/workspace-context' \
  -H "Authorization: Bearer ast_..."

List memory stores

curl 'https://api.agentsky.dev/v1/memory_stores' \
  -H "Authorization: Bearer ast_..."

Create a memory store

curl -X POST https://api.agentsky.dev/v1/memory_stores \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"team-notes","description":"Shared team knowledge base"}'

Get a memory store

curl 'https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x' \
  -H "Authorization: Bearer ast_..."

Update a memory store

curl -X POST https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"team-notes-v2","description":"Updated description"}'

Delete a memory store

curl -X DELETE https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x \
  -H "Authorization: Bearer ast_..."

Archive a memory store (one-way, idempotent)

curl -X POST https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/archive \
  -H "Authorization: Bearer ast_..."

List memories in a store

curl 'https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memories' \
  -H "Authorization: Bearer ast_..."

Create a memory

curl -X POST https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memories \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"path":"/notes/hello","content":"Hello, world"}'

Get a memory with content

curl 'https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memories/mem_cmtc5q1y' \
  -H "Authorization: Bearer ast_..."

Update a memory

curl -X POST https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memories/mem_cmtc5q1y \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello, world v2","precondition":{"type":"content_sha256","content_sha256":"b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"}}'

Delete a memory

curl -X DELETE https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memories/mem_cmtc5q1y \
  -H "Authorization: Bearer ast_..."

List memory versions for a store

curl 'https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memory_versions' \
  -H "Authorization: Bearer ast_..."

Get a single memory version

curl 'https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memory_versions/memver_cmtc5q1z' \
  -H "Authorization: Bearer ast_..."

Redact the content of a memory version

curl -X POST https://api.agentsky.dev/v1/memory_stores/memstore_cmtc5q1x/memory_versions/memver_cmtc5q1z/redact \
  -H "Authorization: Bearer ast_..."

Read your personal cross-session memory

Requires read scope. Only unrestricted owner-facing credentials in the authenticated owner's personal universe are supported; restricted tokens, delegated callers, and team universes return 403.

curl 'https://api.agentsky.dev/v1/memory' \
  -H "Authorization: Bearer ast_..."

Save, edit, remove or clear a personal memory

Requires write scope and unrestricted owner-facing credentials in your personal universe. Read GET /memory first and copy its version exactly into expectedVersion, even when entries is empty. The sample uses null for a store before its first write; replace it with the returned version for an existing document. Stale writes return 409; reload and resolve the change instead of overwriting. Entries are limited to 2048 UTF-8 bytes and the complete recall context to 4000 characters. A state-changing clear advances the version; a no-op on an existing document retains it. Clear preserves allocated indexes.

curl -X POST https://api.agentsky.dev/v1/memory \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"op":"save","text":"Use Celsius for temperatures.","expectedVersion":null}'

Search one platform source: memory, conversations, the trace library, memory notes, files, meeting notes, skills or agents

Searches one platform-owned source in the workspace your key is in. Restricted and delegated callers are refused. The consumer app's `/api/context/search` merges every source (including imports, artifacts and the Help Center) under the same grammar; use it to search everything at once. `q` is plain words (one case-insensitive substring, one hit per item), "an exact phrase" (case-sensitive, every matching line) or /a regex/ with optional i, s or u flags (every matching line). Nested repetition and backreferences are refused, and a pattern stops at a time budget with partial=true. Each hit carries `path` (such as `skills/review/SKILL.md`) and, for a match in the text, its 1-based `line`. Results are in stable source order, not a relevance ranking. Follow nextCursor until null and inspect partial/coverage before concluding no match exists. Memory entries have no per-entry timestamps, so their coverage reports that time filtering does not apply.

curl 'https://api.agentsky.dev/v1/context/search?q=concise&scope=memory' \
  -H "Authorization: Bearer ast_..."

Read the source behind a search hit

Rechecks ownership, workspace and deletion. Accepts memory, session_message, trace_message, memory_note, file, skill_file and agent references from search; a file that is not text reads as text null. Memory returns the current entry and flags version changes; it does not preserve old versions. Message reads return bounded text and adjacent references for surrounding context. Use nextOffset for a long main message; follow adjacent refs to continue reading. All text together is bounded to 20,000 characters per page.

curl 'https://api.agentsky.dev/v1/context/read?ref=%7B%22kind%22%3A%22memory%22%2C%22index%22%3A0%2C%22version%22%3Anull%7D' \
  -H "Authorization: Bearer ast_..."

Caller identity, resolved universe, effective scopes

curl 'https://api.agentsky.dev/v1/whoami' \
  -H "Authorization: Bearer ast_..."

List universes

curl 'https://api.agentsky.dev/v1/universes' \
  -H "Authorization: Bearer ast_..."

Create a universe

Any credential of the person may create one, whichever workspace the request selects with X-Universe. A key limited to one team workspace (a workspace-scoped token, a workspace key or an app credential) is 403 forbidden.

curl -X POST https://api.agentsky.dev/v1/universes \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"acme","name":"Acme"}'

Universe detail

curl 'https://api.agentsky.dev/v1/universes/acme' \
  -H "Authorization: Bearer ast_..."

Rename a workspace

Owner only, as Settings › General renames it. The slug does not change. A credential locked to another workspace is 403 universe_mismatch; a member who is not the owner is 403 forbidden.

curl -X PATCH https://api.agentsky.dev/v1/universes/acme \
  -H "Authorization: Bearer ast_..."

Permanently delete a workspace and everything in it

Owner only, with a personal ast_ API key (a workspace key, a workspace-scoped token or an app credential is 403). Everyone else loses access at once; every session is stopped and its pod destroyed; agent fees held on its tasks are settled; the purchased credit in its wallet goes to the owner; apps the workspace connected are disconnected; then its sessions and transcripts, agents, artifacts, task files, files, memory, routines, channels, webhooks, keys, vaults, skills, environments, traces, members and invitations are removed. Money records (ledger, bills, receipts) are kept. A default workspace cannot be deleted (409 default_workspace), nor one with an agent live in the catalog (409 live_listing), a public environment (409 public_environment) or a published product (409 published_product). 503 pod_teardown_failed when a pod would not stop: nothing else was removed, and repeating the call finishes the delete. Read GET /universes/{slug}/deletion first to show what will go.

curl -X DELETE https://api.agentsky.dev/v1/universes/acme \
  -H "Authorization: Bearer ast_..."

What deleting the workspace would remove, and whether it can be deleted

curl 'https://api.agentsky.dev/v1/universes/acme/deletion' \
  -H "Authorization: Bearer ast_..."

People in the workspace and, for owners and admins, waiting invitations

curl 'https://api.agentsky.dev/v1/universes/acme/members' \
  -H "Authorization: Bearer ast_..."

Remove a non-owner from the workspace, or leave it

The owner removes anyone but themselves. Anyone else may name only themselves (their id, or me), which is how a person leaves; naming someone else is 403, and the owner cannot leave (400). Ends membership access, stops sharing every connection the person shared with the workspace, and closes pending and accepted invitation links. Accounts and threads remain; workspace-visible threads owned by the removed person become read-only for remaining members.

curl -X DELETE https://api.agentsky.dev/v1/universes/acme/members/cmtb3u5r7k2p9x01s6q8n4w2 \
  -H "Authorization: Bearer ast_..."

Make someone an admin or a member

curl -X PATCH https://api.agentsky.dev/v1/universes/acme/members/cmtb3u5r7k2p9x01s6q8n4w2 \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'

The agents this workspace chose from the catalog

The catalog is the same for everyone; this is what the workspace installed from it, enabled or not, with the model members start each agent with by default. agent is the listing as the catalog serves it now, null once it has left the catalog. Installing gates nothing: a policy rule forbids an agent, and starting a session still validates the model it is given.

curl 'https://api.agentsky.dev/v1/universes/acme/agents' \
  -H "Authorization: Bearer ast_..."

One agent the workspace chose from the catalog

curl 'https://api.agentsky.dev/v1/universes/acme/agents/handle' \
  -H "Authorization: Bearer ast_..."

Install an agent from the catalog, or change its default model or enabled state

Idempotent on the handle: the first call installs (201), later calls update (200). The handle must be one the catalog serves to this workspace (404 otherwise). default_model is checked against the agent's engine the way starting a session checks it; null clears it so the agent's own default applies again.

curl -X PUT https://api.agentsky.dev/v1/universes/acme/agents/handle \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"default_model":"claude-sonnet-5"}'

Remove an agent from the workspace's choices

Removes the install and its default model. Sessions already running with the agent are untouched, and members can still start it by handle: use a policy rule to forbid it.

curl -X DELETE https://api.agentsky.dev/v1/universes/acme/agents/handle \
  -H "Authorization: Bearer ast_..."

Add people to the workspace by email

Up to 50 emails per call; the workspace may hold at most 200 pending invitations in total. To invite more than 50 people, send multiple calls. Set send_email to true to send invitation mail and include per-email delivery results. sent means provider acceptance; unavailable leaves a usable link to share. No email is sent and no delivery field is returned by default. The response carries one link token per new invitation (shown only here; links are /join/{token} on the consumer app). Each person joins through the link, or the next time they use AgentSky signed in with that verified email; an invitation lasts 30 days.

curl -X POST https://api.agentsky.dev/v1/universes/acme/invites \
  -H "Authorization: Bearer ast_..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["teammate@acme.com"],"role":"member","send_email":true}'

Withdraw an invitation that has not been taken up

curl -X DELETE https://api.agentsky.dev/v1/universes/acme/invites/cmtb4i7v2n6q8z01s6k3m5p1 \
  -H "Authorization: Bearer ast_..."

A workspace's own wallet: balance, each member's spending this month, limits, members waiting for a higher limit

404 where workspace wallets are not switched on for the workspace, 400 for a person's default workspace that has no wallet and nobody else in it, 403 for a plain member.

curl 'https://api.agentsky.dev/v1/universes/acme/wallet' \
  -H "Authorization: Bearer ast_..."

Give the workspace a wallet of its own

From then on a new session a member starts in the workspace is paid from this wallet unless its request names payer personal, and is refused with 402 workspace_wallet_empty while the wallet holds nothing. Sessions that already exist keep the payer recorded for them. Repeating the call returns the wallet that exists.

curl -X POST https://api.agentsky.dev/v1/universes/acme/wallet \
  -H "Authorization: Bearer ast_..."

Move some of your own purchased credit into the workspace wallet

All or nothing. Only credit the caller bought moves; free credit stays. 402 insufficient_purchased_credit when the caller holds less purchased credit than the amount, 409 workspace_wallet_missing before the wallet exists. request_id makes a repeat of the same request land once (200 instead of 201); the same id with another amount is 409 idempotency_conflict.

curl -X POST https://api.agentsky.dev/v1/universes/acme/wallet/transfers \
  -H "Authorization: Bearer ast_..."

Buy credit for the workspace wallet with your own saved card

Charges the caller's own saved card the credit plus the card processing fee and adds the credit to the workspace wallet. The caller's own balance, card and auto top-up are not changed. amount is 1000, 2000, 5000 or 10000 cents. request_id makes a repeat of the same request charge once (200 instead of 201). 409 card_required when the caller has no saved card (add one to your own account first), 402 card_declined, 409 workspace_wallet_missing before the wallet exists, 503 payments_unavailable where card payments are not set up. A workspace key or a restricted credential cannot buy credit.

curl -X POST https://api.agentsky.dev/v1/universes/acme/wallet/topups \
  -H "Authorization: Bearer ast_..."

Answer a member's request for a higher monthly limit

A member who reaches their monthly limit is not only refused: the task they started or wrote to waits, holding what it was given, and a request is raised (limit_requests on the wallet, and a spend request on the task). raise sets the member's limit to the amount the request offered and sends on what every waiting task of theirs was holding; decline closes this request and drops what its task held. 404 when the request is not open.

curl -X POST https://api.agentsky.dev/v1/universes/acme/wallet/limit-requests/requestId \
  -H "Authorization: Bearer ast_..."

Set or clear a member's monthly limit on workspace wallet spending

The limit counts workspace-wallet charges attributed to that member in the calendar month (UTC): the admitted sender of each turn or consumption, including helpers. Historical charges without a recorded sender and work outside an active turn count against the session starter. At the limit a message to a session the workspace pays for, a helper, a handoff and a fork are refused with 402 member_limit_reached, and a new session is created waiting; other members are not affected. monthly_limit null removes the limit. When the new limit lets the member spend again their waiting tasks continue by themselves: resumed counts the messages that were sent on.

curl -X PUT https://api.agentsky.dev/v1/universes/acme/wallet/limits/cmtb3u5r7k2p9x01s6q8n4w2 \
  -H "Authorization: Bearer ast_..."

Connected apps people share with the workspace, and the ones it owns

sharing says whether members can share connected apps with this workspace; while it is on, can_connect says whether the caller may connect an app for the workspace itself, and a connection the workspace owns carries workspace_owned. A person's default workspace takes shared connections only once someone besides its owner is in it. Agents in the workspace's sessions can call through a shared connection whoever started the session; nobody but the person who shared it holds its sign-in.

curl 'https://api.agentsky.dev/v1/universes/acme/connections' \
  -H "Authorization: Bearer ast_..."

Share one of your own connections with the workspace, or start connecting an app for it

With connection_id: only a connection of the caller's can be shared; answers 201 with the workspace's connections. With app, success_url and error_url (owner or admin): starts connecting an app for the workspace itself and answers 200 with the address to open in a browser; record the result with POST /universes/{slug}/connections/complete. A connection made this way belongs to the workspace, not to the person who made it, and stays when they leave.