---
title: API Getting Started
description: Connect to the Apptonomy Public API — the plan and role you need, creating an API key, the base URL, authenticating with the key, and a first request with curl.
---

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](/docs/mcp/getting-started).

## Before you start

- **A plan with API access.** API keys need the **Enterprise** plan (see [Plans & Entitlements](/docs/billing/plans-and-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](/docs/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](/docs/api/keys) 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:

```bash
read -rs APPTONOMY_API_KEY && export APPTONOMY_API_KEY
```

Then read the organization the key belongs to:

```bash
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](/docs/api/conventions#errors) lists every code.

## Next steps

- [Resources](/docs/api/resources) — everything the API reads, with the scope each read needs
- [Actions](/docs/api/actions) — starting audits, writing draft listings and changing a recommendation's state
- [Weekly Report Example](/docs/api/weekly-report-example) — a complete walkthrough in curl and JavaScript
- [Conventions](/docs/api/conventions) — the OpenAPI document, pagination, provenance, errors, rate limits and versioning

:::note[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.
