# Choose the AirPrompter API surface

Decide between the customer REST API, MCP, Connect, and the browser extension, then make a verified request without assuming unsupported endpoints.

AirPrompter has more than one integration surface because reading account metadata, running a saved workflow, and controlling a browser chat are different jobs. Start with the outcome you need, then choose the smallest surface that supports it.

**REST reads are available; host actions vary**

`GET /v1/me` and `GET /v1/entitlements` are current customer REST API routes. MCP and Connect actions can vary by host, OAuth scopes, account access, and rollout, which is why this mixed decision page is marked **Availability varies**.

![One saved-system source branching into a short two-card API path and a longer prompt-and-workflow connection path](https://airprompter.com/docs/illustrations/api-access-map.webp)

Choose the smallest integration surface that supports the job: bounded REST reads or richer MCP prompt and workflow actions. [Open full-size illustration](https://airprompter.com/docs/illustrations/api-access-map.webp)

## Choose the right surface

| You need to                                                     | Use                                                                                        | Current boundary                                              |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| Read the identity associated with a customer API key            | REST API                                                                                   | `GET /v1/me`                                                  |
| Read the key owner’s entitlement projection                     | REST API                                                                                   | `GET /v1/entitlements`                                        |
| Discover prompts or workflows and run an ordered workflow       | [MCP](https://airprompter.com/docs/mcp) or [Connect](https://airprompter.com/docs/connect) | Tools exposed to the authenticated connection                 |
| Create or update prompts and workflows from an eligible AI host | OAuth-based MCP connection                                                                 | Requires the host action, `prompts.write`, and account access |
| Run a saved sequence beside a supported browser AI chat         | [Browser extension](https://airprompter.com/docs/browser-extension)                        | Uses the extension’s visible Send, Copy, and Run All controls |
| Manage API keys                                                 | AirPrompter **Account → Developer**                                                        | Authenticated web-app action, not a customer `/v1` endpoint   |

**The REST API is intentionally small today**

The current REST API does not provide prompt or workflow CRUD. Do not invent an endpoint from an internal web-app route or assume that an MCP tool also exists as REST.

## Before you make a REST request

You need:

- an AirPrompter account with access to [**Account → Developer**](https://airprompter.com/account/developer);
- a newly created API key stored in a secure secret manager or environment variable;
- the target and content environment appropriate for the job; and
- a client that can send an HTTPS request with an authorization header.

Read [Create and protect API keys](https://airprompter.com/docs/api-keys) before creating a production credential.

## Make the smallest proof request

1. Create a read-only key for the intended target in **Account → Developer**.
2. Save the complete show-once value in a protected runtime secret.
3. Export that value to the client process without printing it.
4. Call `GET /v1/me` with a Bearer authorization header.
5. Compare the returned identity with the account the job is expected to use.
6. Stop and revoke the key if the identity is unexpected.

The production base URL is:

```text
https://api.airprompter.com
```

Store the complete secret outside source code:

```sh
export AIRPROMPTER_API_KEY="your-key-from-the-show-once-dialog"
```

Then request the key-associated identity:

```sh
curl --fail-with-body \
  --header "Authorization: Bearer $AIRPROMPTER_API_KEY" \
  https://api.airprompter.com/v1/me
```

AirPrompter also accepts the customer credential in `X-Api-Key`, but a Bearer header is the clearest default for a new integration. Never include the real value in a shell-history screenshot, issue, chat message, or documentation example.

**Expected result:** the API returns JSON for the identity resolved from that active key. It must not return another account’s identity.

The response follows this client-safe shape; the values below are deliberately redacted examples:

```json
{
  "actor": {
    "userId": "redacted-user-id",
    "apiKeyId": "redacted-api-key-id"
  },
  "personal": {
    "accountMode": "individual",
    "libraryId": "redacted-library-id"
  },
  "workspaces": [
    {
      "workspaceId": "redacted-workspace-id",
      "organizationId": "redacted-organization-id",
      "displayName": "Example workspace",
      "roleId": "redacted-role-id",
      "membershipStatus": "active"
    }
  ]
}
```

`displayName` is optional. `membershipStatus` is `active` or `removed`; do not treat a returned workspace row as permission to bypass the operation’s normal authorization checks.

## Read the entitlement projection

After identity succeeds, request the current entitlement projection:

```sh
curl --fail-with-body \
  --header "Authorization: Bearer $AIRPROMPTER_API_KEY" \
  https://api.airprompter.com/v1/entitlements
```

**Expected result:** the API returns the entitlement view for the same key owner and target context.

Use the top-level fields as follows:

| Field                                                  | Meaning                                                                         |
| ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `schemaVersion`                                        | Version of the public entitlement response shape                                |
| `actor`                                                | Redacted-safe identifiers for the resolved user and API key                     |
| `tier`, `effectiveTier`, subscription and trial fields | Current plan/subscription projection                                            |
| `features`                                             | Named service-availability booleans                                             |
| `access`                                               | Backend-produced access projection; do not reconstruct it from tier names       |
| `accountAccess`                                        | Versioned Personal/Workspace context summaries, source, update time, and counts |

**Entitlements are not workspace authorization**

An entitlement describes plan or service availability. It does not independently grant access to an organization, workspace, prompt, workflow, or Playbook.

## Use MCP for prompt and workflow work

Choose MCP when your program is an AI host that should discover AirPrompter tools, retrieve saved instructions, or continue a workflow. The production MCP endpoint is:

```text
https://mcp.airprompter.com
```

Interactive host connections normally use OAuth so the user can review `prompts.read` and, when supported, `prompts.write`. The host remains the model runtime: AirPrompter supplies saved instructions and run state; the host executes the work with its available conversation, files, web access, and native tools.

Use [Connect an AI host](https://airprompter.com/docs/connect) for supported product-led installation. Use [Direct MCP connections](https://airprompter.com/docs/mcp) only when the current host is documented or approved for manual configuration.

## Apply the API to day-to-day work

### Verify a headless job before it starts

Have the job call `/v1/me` at startup and compare the returned identity with the expected non-secret account reference in your deployment configuration. Stop the job if the credential resolves to the wrong owner or fails authentication.

### Gate an integration’s optional behavior

Read `/v1/entitlements` when your integration needs to display or skip a plan-dependent AirPrompter capability. Keep resource authorization separate; do not infer workspace membership from that response.

### Let an agent run a saved process

Do not poll REST for a fictional workflow endpoint. Connect the agent through MCP, ask it to find the workflow by name, resolve ambiguous matches, provide required inputs, and continue the saved sequence.

## Troubleshooting

### The API returns `401 Unauthorized`

Confirm that the entire key was copied from the show-once dialog, the key is active and unexpired, the header starts with `Bearer `, and no quote or newline became part of the value. If the secret was lost or exposed, revoke it and create a replacement.

### A REST route returns `404`

Check the method and exact path. The currently documented customer routes are only `GET /v1/me` and `GET /v1/entitlements`. An internal `/api-keys` route, MCP tool name, or web-app path is not a public `/v1` route.

### You need prompt or workflow data

Use the [MCP decision and setup guide](https://airprompter.com/docs/mcp). Do not guess a REST endpoint or scrape the authenticated web application.

### A Team write is denied

Organization- and workspace-bound API keys remain read-only even if a client requests a write scope. Use an eligible OAuth MCP connection for Team writes and let the normal authorization boundary decide access.

## Completion checklist

- You chose REST only for a currently documented REST outcome.
- The credential is stored outside source control and logs.
- `/v1/me` resolves the intended key owner.
- `/v1/entitlements` is treated as a projection, not resource authority.
- Prompt and workflow operations use MCP rather than invented REST paths.
- Your integration stops safely on an unexpected identity or authentication failure.

## Next steps

Create a least-privilege credential with [API keys and scopes](https://airprompter.com/docs/api-keys), or configure an eligible host with [Direct MCP connections](https://airprompter.com/docs/mcp).

---

Canonical: https://airprompter.com/docs/api