API Getting Started

3 min readLast updated View as MarkdownAgent setup

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 wrongAnswer
No Authorization header, or not Bearer401 unauthenticated
Key unknown, revoked or expired401 invalid_credential
Key anywhere in the URL400 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

Apptonomy does not send outbound webhooks. To follow audits and publishes from your own code, read them from the API.