REST API
Everything the console does goes through this API — there are no private endpoints with extra powers. Base URL: https://animica.dev/api/cloud/v1. All money fields are integer nANM strings.
Authentication
two ways in
# API key (create in the Developer Center; scoped, prefix anm_mkt_)
curl -H "authorization: Bearer anm_mkt_…" https://animica.dev/api/cloud/v1/me
# or a signed-in browser session cookie (the console uses this)Write operations accept an idempotency-key header — retrying with the same key returns the original result instead of repeating the action. Errors are uniform:
error shape
{ "error": { "code": "insufficient_funds", "message": "…", "details": { … } } }Notable codes: 401 unauthorized · 402 insufficient_funds / quota_exceeded / plan_limit / billing_past_due · 403 capability_denied / suspended / code_denied · 409 conflict / not_active · 422 validation_failed / unsupported_package · 429 rate_limited / concurrency_limit / free_tier_limit · 503 busy / validator_unavailable / disabled.
Execution
| method | path | purpose | auth |
|---|---|---|---|
GET/POST | /fn/{owner}/{slug} | the public endpoint of a deployed function — GET query params or POST JSON body become the function's request; CORS-open | optional* |
POST | /functions/{id}/invoke | authenticated invoke by id: { payload?, maxSpendNanm? } — the console's Run button; returns result + logs + full receipt | key/session |
POST | /estimate | pre-execution price estimate: typical + worst case, full per-line breakdown, at your real fee rate | key/session |
POST | /validate | the exact deploy-time static validator, for editors (findings with line numbers) | key/session |
* anonymous callers reach public, auth-optional, zero-surcharge functions inside the free tier.
cost headers on every /fn response
x-animica-request-id: rq_… # ties the response to the execution + receipt
x-animica-cost-nanm: 5255894 # exact charge for this call, integer nANM
x-animica-status: succeeded # succeeded | failed | timeoutFunctions & deployments
| method | path | purpose | auth |
|---|---|---|---|
GET | POST | /functions | list my functions · create a function shell | key/session |
GET | PATCH | DELETE | /functions/{id} | detail · update config (slug immutable) · archive (history preserved) | key/session |
GET | POST | /functions/{id}/versions | immutable version history · push new source as version max+1 and deploy it | key/session |
POST | /functions/{id}/deploy | {version?} redeploy an existing version · {deploymentId?} resume a stalled attempt | key/session |
POST | /functions/{id}/rollback | {version} — a NEW deployment of an OLD version | key/session |
GET | /functions/{id}/deployments | deployment history with per-step logs and anchor status | key/session |
GET | /functions/{id}/executions | execution history: status, usage, exact money | key/session |
GET | /functions/{id}/logs | execution logs, secret-redacted, cursor-paged | key/session |
Apps & marketplace
| method | path | purpose | auth |
|---|---|---|---|
GET | POST | /apps | public catalog (filters, real popularity) · create an app | public / key |
GET | PATCH | /apps/{slug} | listing detail · update my app | key/session |
POST | /apps/{slug}/publish | publish / unpublish | key/session |
POST | /apps/{slug}/purchase | buy (one-time or subscription period) — exact split settlement | key/session |
POST | /apps/{slug}/authorize | grant the app capabilities with spend bounds | key/session |
GET | POST | /apps/{slug}/reviews | reviews (verified users only) | key/session |
POST | /reports | report an app / function / developer | public / key |
Agents, schedules, secrets, grants
| method | path | purpose | auth |
|---|---|---|---|
GET | POST | /agents | list my agents · create (function binding, budgets, own address) | key/session |
GET | PATCH | DELETE | /agents/{slug} | detail · pause/resume/update budgets · delete | key/session |
POST | /agents/{slug}/run | run the agent now (budgets enforced server-side) | key/session |
GET | POST | PATCH | DELETE | /schedules | CRUD scheduled invocations (interval or 5-field UTC cron) | key/session |
GET | POST | DELETE | /secrets | names+hints only · create/rotate (values are write-only) · delete | key/session |
GET | POST | DELETE | /grants | my authorizations · create/update · revoke (immediate) | key/session |
Account
| method | path | purpose | auth |
|---|---|---|---|
GET | /me | resolved plan + entitlements + LIVE usage against every limit + balance + credits | key/session |
GET | /me/earnings | settled vs pending earnings, by function and by day | key/session |
GET | /me/analytics | execution analytics for my functions | key/session |
GET | POST | /developers/handle | claim / check my public handle | key/session |
GET | /developers/{handle} | public developer profile | public |
POST | /enterprise | enterprise / dedicated-capacity inquiry | public |
Compute providers (the fleet)
| method | path | purpose | auth |
|---|---|---|---|
POST | /providers/register | self-register a provider (payout address, capabilities); bearer token minted/held by you | provider token |
POST | /providers/claim | atomically claim the next job (lease-based; 204 when none) | provider token |
POST | /providers/heartbeat | liveness + extend a job lease | provider token |
POST | /providers/result | submit a job outcome — settles the provider share as spendable ANM | provider token |
POST | /providers/fail | report a failed attempt (bounded retries) | provider token |
GET | /providers/runtime | the runtime image + protocol the fleet must run | provider token |
GET | /providers | public fleet stats | public |
Admin endpoints exist under
/api/cloud/v1/admin/* (pricing policy versions, finance rollups, reconciliation reports, denylist, suspensions…). They require platform-admin auth and are documented in the operator reference (docs/python-cloud.md in the repository), not here.