Frontmost AI API

Use this API to read how AI apps answer your buyers' questions about your business, and to change what Frontmost AI tracks. It gives a coding agent the same numbers as the Frontmost AI app and the MCP server.

• Base URL: https://app.frontmost.ai/api/v1
• OpenAPI 3.1 file: https://app.frontmost.ai/api/v1/openapi.json
• This page as Markdown: https://app.frontmost.ai/docs/api.md

Get a key

1. Open https://app.frontmost.ai/team and go to API Keys.
2. Name the key and choose what it can do. A Read Only key calls every GET route. A Read and Write key calls every route.
3. Copy the key when it appears. Frontmost AI shows it once.

Every plan includes API keys. Every member of a workspace can create keys, see every key, and revoke any key. A revoked key stops working on the next request.

Authenticate

Send the key in the Authorization header of every request:

curl https://app.frontmost.ai/api/v1/workspace \
  -H "Authorization: Bearer $FRONTMOST_API_KEY"

Keep the key in an environment variable such as FRONTMOST_API_KEY. Do not put it in code that you commit.

First call

Call GET /workspace first. It returns the plan, its limits, and what is in use. Then call GET /projects to find project IDs.

curl https://app.frontmost.ai/api/v1/projects \
  -H "Authorization: Bearer $FRONTMOST_API_KEY"

Routes

The OpenAPI file has every parameter and response field.

Create a project

A new project starts from a website. Frontmost AI reads the site, then writes the first questions.

1. Send POST /projects with domain and an Idempotency-Key header. Use a new random key, for example a UUID, for each new project.
2. A ready project returns 201 with the project object.
3. A setup that needs more time returns 202 with a project_setup object and a Retry-After: 30 header. Its next field holds the exact next call.
4. Wait Retry-After seconds. Send POST /projects with {"setup_id": "…"} and no Idempotency-Key. Repeat steps 2 to 4.

A repeated call never makes a second project. A site that Frontmost AI cannot read returns 422 site_unreadable.

curl -X POST https://app.frontmost.ai/api/v1/projects \
  -H "Authorization: Bearer $FRONTMOST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

The same Idempotency-Key with the same body returns the first reply with Idempotent-Replayed: true. The same key with another body returns 409 idempotency_conflict. Frontmost AI keeps each key for 24 hours.

Scope

The metrics, rivals, answers, and sources routes take the same scope parameters:

• A week or month is the calendar week or month, in US Eastern time, that holds the anchor scan. It does not end at scan_id.
• previous is the same kind of period that ends at the last delivered scan before this one starts.
• Each rate comes from pooled counts: {"value", "numerator", "denominator", "previous"}. Report the counts with the rate, for example "22% · 8 of 36 answers".
• Every response states its scope: the anchor scan, the dates, the scans counted, the apps, the question set, and the comparison.
• scope.definitions_version changes when a counting rule changes.
• A project with no delivered scan returns "scope": null and empty lists.

Lists

A list returns {"object": "list", "data": [...], "has_more": true, "next_cursor": "…"}. limit is 1 to 100, and the default is 25. To get the next page, send the same request with cursor set to next_cursor. A cursor works only with the list and parameters that made it.

Errors

Every error has this shape. The message says what to do next. Quote request_id when you report a problem.

{
  "error": {
    "code": "invalid_param",
    "message": "period must be scan, week, or month.",
    "param": "period",
    "request_id": "req_…"
  }
}

A route that exists with another method returns 404, and the message names the methods it takes.

Rate limits

Each key has one budget for reads and one for changes. A browser sign-in has the same two budgets for each person. A month scope costs more than a scan or a week. Read the headers on every response. Do not hard-code the numbers, because they can change.

HTTP/2 429
Retry-After: 3
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 3

On a 429, wait Retry-After seconds plus a short random delay, then send the request again.

Compatibility

• New fields can appear in any response. Ignore fields that you do not know.
• Lists of values, such as AI apps and codes, can grow. Treat an unknown value as "other".
• IDs are strings. They match the IDs in app URLs, for example the 16 in /projects/16.
• A change that removes or renames a field goes to /v2.

Command line

The Frontmost AI CLI calls this API from a terminal. Each route on this page is a command.

brew install frontmost-ai/tap/frontmost
frontmost login
frontmost metrics --period week

Without Homebrew, run npm install -g github:frontmost-ai/cli. It needs Node.js 22.12 or later. Add --json to any command to get the API response, unchanged. Source: https://github.com/frontmost-ai/cli

Use with a coding agent

Give the agent the key and this page:

export FRONTMOST_API_KEY=fmk_…
# Docs: https://app.frontmost.ai/docs/api.md

To connect an AI app such as Claude or ChatGPT instead, use the MCP server: https://frontmost.ai/connect