API reference

Read-only REST API. All endpoints under /api/v1/*.

Auth probe

Verifies the API key works and echoes the resolved org.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Response Body

curl -X GET "https://api.42a.ai/api/v1/_health"

{
  "data": {
    "ok": true,
    "organization_id": "j97abc...",
    "organization_name": "Acme Inc",
    "key_type": "org"
  },
  "next_cursor": null,
  "meta": {
    "request_id": "5c9d4305-...",
    "took_ms": 41
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Caller identity

Returns the authenticated principal plus the orgs the caller can access. No org context required.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Response Body

curl -X GET "https://api.42a.ai/api/v1/me"

{
  "data": {
    "key_type": "user",
    "key_id": "ak_xxx",
    "subject": "user_2abc",
    "active_organization_id": null,
    "accessible_organizations": [
      {
        "id": "org_2acme",
        "name": "Acme Inc",
        "role": "admin"
      },
      {
        "id": "org_2globex",
        "name": "Globex",
        "role": "basic_member"
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 38
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

List accessible organizations

For org keys, returns a single-element list. For user keys, returns every org the user belongs to that exists in 42A.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Response Body

curl -X GET "https://api.42a.ai/api/v1/organizations"

{
  "data": [
    {
      "id": "org_2acme",
      "name": "Acme Inc",
      "role": "admin"
    }
  ],
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 22
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

List projects

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

limit?integer

Page size, 1-100. Defaults to 25.

Default25

Range1 <= value <= 100

cursor?string

Opaque cursor returned in the previous page's next_cursor.

active?boolean

When true, return only active projects.

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/projects?limit=25&cursor=string&active=true" \
  -H "X-Org-Id: string"

{
  "data": [
    {
      "id": "prj_j97abc",
      "organization_id": "j97org",
      "name": "Q2 Brand Tracking",
      "description": "Multi-provider visibility scan",
      "is_active": true,
      "config_type": "brand",
      "schedule": {
        "type": "weekly",
        "time": "09:00",
        "day_of_week": 1,
        "day_of_month": null
      },
      "brand_ids": [
        "brn_j97a"
      ],
      "prompt_template_ids": [
        "prm_j97p"
      ],
      "provider_ids": [
        "j97prov"
      ],
      "location_ids": [],
      "created_at": 1730000000000,
      "updated_at": 1730000099999
    }
  ],
  "next_cursor": "eyJpZCI6Im...",
  "meta": {
    "request_id": "...",
    "took_ms": 53
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Fetch a single project

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed project id, e.g. prj_xxx.

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/projects/string" \
  -H "X-Org-Id: string"

Empty

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Top mentioned brands in a project

Leaderboard of brands by mention count within a project's analysis window. Aggregates brandMentions over the chosen period. Capped at a max scan size; if truncated is true, narrow the period.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed project id, e.g. prj_xxx.

Query Parameters

period?string

Default"30d"

Value in"7d" | "30d" | "90d"

limit?integer

Default10

Range1 <= value <= 100

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/projects/string/top-brands?period=7d&limit=10" \
  -H "X-Org-Id: string"

{
  "data": {
    "project_id": "prj_j97abc",
    "project_name": "Q2 Brand Tracking",
    "period": "7d",
    "date_from": "2026-04-26",
    "date_to": "2026-05-03",
    "truncated": false,
    "items": [
      {
        "brand_id": "brn_acme",
        "name": "Acme",
        "mention_count": 184
      },
      {
        "brand_id": "brn_globex",
        "name": "Globex",
        "mention_count": 132
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 71
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Leaderboard of prompt templates by mention count within a project's analysis window. Aggregates brandMentions over the chosen period. Capped at 5,000 mention rows scanned; if truncated is true, narrow the period to get accurate counts.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed project id, e.g. prj_xxx.

Query Parameters

period?string

Default"30d"

Value in"7d" | "30d" | "90d"

limit?integer

Default10

Range1 <= value <= 100

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/projects/string/top-prompts?period=7d&limit=10" \
  -H "X-Org-Id: string"

{
  "data": {
    "project_id": "prj_j97abc",
    "project_name": "Q2 Brand Tracking",
    "period": "7d",
    "date_from": "2026-04-26",
    "date_to": "2026-05-03",
    "truncated": false,
    "items": [
      {
        "prompt_template_id": "prm_j97p1",
        "name": "Best CRM for early-stage SaaS",
        "category": "comparison",
        "version": 3,
        "is_active": true,
        "mention_count": 156
      },
      {
        "prompt_template_id": "prm_j97p2",
        "name": "Top sales-engagement tools",
        "category": "awareness",
        "version": 1,
        "is_active": true,
        "mention_count": 92
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 73
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Top cited websites in a project

Leaderboard of websites by citation count within a project's analysis window. Aggregates citations over the chosen period.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed project id, e.g. prj_xxx.

Query Parameters

period?string

Default"30d"

Value in"7d" | "30d" | "90d"

limit?integer

Default10

Range1 <= value <= 100

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/projects/string/top-websites?period=7d&limit=10" \
  -H "X-Org-Id: string"

{
  "data": {
    "project_id": "prj_j97abc",
    "project_name": "Q2 Brand Tracking",
    "period": "7d",
    "date_from": "2026-04-26",
    "date_to": "2026-05-03",
    "truncated": false,
    "items": [
      {
        "website_id": "j93web1",
        "domain": "techcrunch.com",
        "apex_domain": "techcrunch.com",
        "type": "news_article",
        "citation_count": 47
      },
      {
        "website_id": "j93web2",
        "domain": "wikipedia.org",
        "apex_domain": "wikipedia.org",
        "type": "academic",
        "citation_count": 31
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 88
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

List prompt templates

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

limit?integer

Page size, 1-100. Defaults to 25.

Default25

Range1 <= value <= 100

cursor?string

Opaque cursor returned in the previous page's next_cursor.

active?boolean

category?string

One of awareness, consideration, comparison, technical.

Value in"awareness" | "consideration" | "comparison" | "technical"

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/prompts?limit=25&cursor=string&active=true&category=awareness" \
  -H "X-Org-Id: string"

Empty

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Fetch a single prompt template

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed prompt id, e.g. prm_xxx.

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/prompts/string" \
  -H "X-Org-Id: string"

Empty

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Top brands mentioned through a prompt

Leaderboard of brands by mention count, restricted to mentions surfaced through a single prompt template. Useful for understanding which brands a particular prompt tends to elevate.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed prompt-template id, e.g. prm_xxx.

Query Parameters

period?string

Default"30d"

Value in"7d" | "30d" | "90d"

limit?integer

Default10

Range1 <= value <= 100

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/prompts/string/top-brands?period=7d&limit=10" \
  -H "X-Org-Id: string"

{
  "data": {
    "prompt_template_id": "prm_j97p1",
    "prompt_name": "Best CRM for early-stage SaaS",
    "category": "comparison",
    "period": "7d",
    "date_from": "2026-04-26",
    "date_to": "2026-05-03",
    "truncated": false,
    "items": [
      {
        "brand_id": "brn_acme",
        "name": "Acme",
        "mention_count": 42
      },
      {
        "brand_id": "brn_globex",
        "name": "Globex",
        "mention_count": 31
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 51
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

List brands

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

limit?integer

Page size, 1-100. Defaults to 25.

Default25

Range1 <= value <= 100

cursor?string

Opaque cursor returned in the previous page's next_cursor.

tracking?string

Value in"tracked" | "ignored" | "new"

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/brands?limit=25&cursor=string&tracking=tracked" \
  -H "X-Org-Id: string"

Empty

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Fetch a single brand

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed brand id, e.g. brn_xxx.

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/brands/string" \
  -H "X-Org-Id: string"

Empty

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Brand visibility stats

Period-aggregated visibility metrics for a single brand. Includes a daily history series for charting. Use this to answer "how did my brand visibility improve?" or "how many times was my brand mentioned?"

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

idstring

Prefixed brand id, e.g. brn_xxx.

Query Parameters

period?string

Default"30d"

Value in"7d" | "30d" | "90d"

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/brands/string/stats?period=7d" \
  -H "X-Org-Id: string"

{
  "data": {
    "brand_id": "brn_j97a",
    "brand_name": "Acme",
    "period": "7d",
    "date_from": "2026-04-26",
    "date_to": "2026-05-03",
    "visibility_score": 0.42,
    "mention_count": 184,
    "total_queries": 521,
    "queries_with_mentions": 210,
    "mention_coverage": 0.4031,
    "avg_position": 3.7,
    "sentiment_score": 0.21,
    "trend": {
      "score_change": 0.05,
      "mention_change": 28,
      "position_change": -0.4
    },
    "history": [
      {
        "date": "2026-04-26",
        "visibility_score": 0.39,
        "mention_count": 22
      },
      {
        "date": "2026-04-27",
        "visibility_score": 0.4,
        "mention_count": 26
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 64
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

List topics in your org

Returns the topics that classify at least one of your org's prompt templates. Topics are auto-generated by an LLM classifier; each topic has a stable slug, a human-readable name, and a description.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

limit?integer

Page size, 1-100. Defaults to 25.

Default25

Range1 <= value <= 100

cursor?string

Opaque cursor returned in the previous page's next_cursor.

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/topics?limit=25&cursor=string" \
  -H "X-Org-Id: string"

{
  "data": [
    {
      "id": "tpc_j7t1",
      "slug": "ai-coding-assistants",
      "name": "AI Coding Assistants",
      "description": "Tools that generate or assist with code via LLMs.",
      "is_auto_generated": true,
      "status": "active",
      "created_at": 1730000000000,
      "updated_at": 1730000099999
    },
    {
      "id": "tpc_j7t2",
      "slug": "developer-search",
      "name": "Developer Search",
      "description": "Stack Overflow-style developer Q&A surfaces.",
      "is_auto_generated": true,
      "status": "active",
      "created_at": 1730000000000,
      "updated_at": 1730000099999
    }
  ],
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 122
  }
}

List citations

Exactly one of project_id, prompt_id, or website_id is required so the query always hits a covering index.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

limit?integer

Page size, 1-100. Defaults to 25.

Default25

Range1 <= value <= 100

cursor?string

Opaque cursor returned in the previous page's next_cursor.

project_id?string

Prefixed project id prj_xxx. Mutually exclusive with prompt_id/website_id.

prompt_id?string

Prefixed prompt id prm_xxx. Mutually exclusive with project_id/website_id.

website_id?string

Raw Convex website id (no prefix). Mutually exclusive with project_id/prompt_id.

from?string

Inclusive lower bound, ISO-8601 date.

Formatdate-time

to?string

Inclusive upper bound, ISO-8601 date.

Formatdate-time

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/citations?limit=25&cursor=string&project_id=string&prompt_id=string&website_id=string&from=2019-08-24T14%3A15%3A22Z&to=2019-08-24T14%3A15%3A22Z" \
  -H "X-Org-Id: string"

Empty

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Org-level visibility rollup

Aggregates brandScores over the requested period.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

period?string

Rolling window. Defaults to 30d.

Default"30d"

Value in"7d" | "30d" | "90d"

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/vitals?period=7d" \
  -H "X-Org-Id: string"

{
  "data": {
    "period": "30d",
    "date_from": "2026-04-03",
    "date_to": "2026-05-03",
    "visibility_score": 0.42,
    "mention_count": 1840,
    "total_queries": 5210,
    "queries_with_mentions": 2104,
    "mention_coverage": 0.4038,
    "avg_position": 3.7,
    "sentiment_score": 0.21,
    "trend": {
      "score_change": 0.05,
      "mention_change": 280,
      "position_change": -0.4
    }
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 88
  }
}

Visibility breakdown by prompt category

Aggregates org-wide visibility metrics by prompt-template category (awareness, consideration, comparison, technical, plus uncategorized for prompts without a category set).

Sorted by visibility_score descending - the first item is the org's strongest vertical. Use this to answer "what is my strongest vertical?".

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

period?string

Default"30d"

Value in"7d" | "30d" | "90d"

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/vitals/by-category?period=7d" \
  -H "X-Org-Id: string"

{
  "data": {
    "period": "30d",
    "date_from": "2026-04-03",
    "date_to": "2026-05-03",
    "items": [
      {
        "category": "awareness",
        "visibility_score": 0.51,
        "mention_count": 920,
        "total_queries": 1800,
        "avg_position": 2.9,
        "prompt_template_count": 4
      },
      {
        "category": "comparison",
        "visibility_score": 0.38,
        "mention_count": 410,
        "total_queries": 1100,
        "avg_position": 4.1,
        "prompt_template_count": 3
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 102
  }
}

Top cited websites in a vertical (prompt category)

Leaderboard of websites by citation count, restricted to a "vertical" (prompt-template category). Aggregates citations across every prompt template in the org with the matching category.

Supported categories: awareness, consideration, comparison, technical. The truncated flag indicates whether the per-template scan cap was hit (i.e. an unusually citation-heavy prompt).

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Path Parameters

categorystring

Value in"awareness" | "consideration" | "comparison" | "technical"

Query Parameters

period?string

Default"30d"

Value in"7d" | "30d" | "90d"

limit?integer

Default10

Range1 <= value <= 100

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/categories/awareness/top-websites?period=7d&limit=10" \
  -H "X-Org-Id: string"

{
  "data": {
    "category": "comparison",
    "prompt_template_count": 4,
    "citations_scanned": 832,
    "period": "7d",
    "date_from": "2026-04-26",
    "date_to": "2026-05-03",
    "truncated": false,
    "items": [
      {
        "website_id": "j93web1",
        "domain": "g2.com",
        "apex_domain": "g2.com",
        "type": "review_site",
        "citation_count": 73
      },
      {
        "website_id": "j93web2",
        "domain": "techcrunch.com",
        "apex_domain": "techcrunch.com",
        "type": "news_article",
        "citation_count": 41
      }
    ]
  },
  "next_cursor": null,
  "meta": {
    "request_id": "...",
    "took_ms": 96
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

Tracked pages and their feature scores

For a given brand, returns the tracked pages with citation counts and latest per-feature scores. Required: brand_id.

Authorization

AuthorizationBearer <token>

42A API key (org or user).

In: header

Query Parameters

limit?integer

Page size, 1-100. Defaults to 25.

Default25

Range1 <= value <= 100

cursor?string

Opaque cursor returned in the previous page's next_cursor.

brand_idstring

Prefixed brand id, e.g. brn_xxx.

tracked?boolean

When false, also include untracked pages. Defaults to true.

Defaulttrue

sort?string

Pagination order. score_low returns the worst-scoring pages first and is the right choice for "what should I improve?" questions.

Default"recent"

Value in"recent" | "score_low" | "score_high" | "citations" | "last_checked"

Header Parameters

X-Org-Id?string

Organization id, e.g. org_xxx. Required when authenticating with a user API key on org-scoped endpoints. Ignored for org keys (or validated to match - defense in depth).

Match^org_

Response Body

curl -X GET "https://api.42a.ai/api/v1/page-vitals?limit=25&cursor=string&brand_id=string&tracked=true&sort=recent" \
  -H "X-Org-Id: string"

Empty

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "request_id": "string"
  }
}

API reference

200

401

Example default

200

401

Example userKey

200

401

Example default

200

400

401

Example default

200

404

200

404

Example default

200

404

Example default

200

404

Example default

200

401

200

404

200

404

Example default

200

401

200

404

200

404

Example default

200

Example default

200

404

Example default

200

404

Example default

200

400

401

200

Example default