API Getting Started
The Public API lets your own code — a data warehouse sync, a reporting script, a CI job — read your organization’s Apptonomy data and start its actions. This page takes you from nothing to a first authenticated request. AI clients such as Claude don’t use the API; they connect through MCP.
Before you start
- A plan with API access. API keys need the Enterprise plan (see Plans & Entitlements). On another plan, requests answer
403 entitlement_required. - An Owner or Manager. Only they see Org Settings › API Access, where keys are created.
1. Create a key
In Apptonomy, open Org Settings › API Access, click Create API key, name it after the system that will use it, and tick the scopes it needs — organization:read is enough for the request below. Apptonomy shows the full key once: copy it into your secret manager before you close the dialog. API Keys covers scopes, expiry, rotation and what to do if a key leaks.
A key belongs to the organization, not to you, and reaches only the organization it was created in.
2. The base URL
https://api.apptonomy.ai/v1
The major version is part of the path. Responses are JSON (application/json); a request whose Accept header excludes JSON answers 406 not_acceptable, and a method a path doesn’t take answers 405 method_not_allowed, with an Allow header listing the ones it does. Reads are GET; actions are POST with a JSON body.
3. Authenticate
Send an organization API key as a bearer token:
Authorization: Bearer a7y_live_<key id>_<secret>
| What went wrong | Answer |
|---|---|
No Authorization header, or not Bearer | 401 unauthenticated |
| Key unknown, revoked or expired | 401 invalid_credential |
| Key anywhere in the URL | 400 invalid_request, detail credential_in_url — revoke that key |
A key is the organization’s own credential and acts for the organization, never for a person. It reaches exactly one organization — the one it was created in — so the organization is never a parameter.
4. Make a first request
Put the key in an environment variable rather than pasting it into commands, so it doesn’t end up in your shell history:
read -rs APPTONOMY_API_KEY && export APPTONOMY_API_KEY
Then read the organization the key belongs to:
curl -s https://api.apptonomy.ai/v1/organization \
-H "Authorization: Bearer $APPTONOMY_API_KEY" \
-H "Accept: application/json"
A 200 answer carries the organization in data — its id, name, slug, timezone, iconUrl, createdAt and updatedAt — and a meta.requestId to quote if you contact support. A 401 or 403 names what is wrong in error.code; Errors lists every code.
Next steps
- Resources — everything the API reads, with the scope each read needs
- Actions — starting audits, writing draft listings and changing a recommendation’s state
- Weekly Report Example — a complete walkthrough in curl and JavaScript
- Conventions — the OpenAPI document, pagination, provenance, errors, rate limits and versioning
The app’s own API is not for integrations
Every other path on api.apptonomy.ai — for example /apptonomy/project — serves Apptonomy’s own web app and Figma plugin. Those endpoints authenticate with the app’s short-lived sign-in session, carry no compatibility guarantee and can change in any release. Build on /v1 instead.
Apptonomy does not send outbound webhooks. To follow audits and publishes from your own code, read them from the API.