Skip to main content
The Notra API is a REST API served from https://api.usenotra.com. Everything the dashboard can do with GEO tracking, content, schedules, chats, skills and agent feedback is available over HTTP. The full contract is an OpenAPI 3.1 document at api.usenotra.com/openapi.json.

REST API

Call endpoints directly with curl or fetch, which works for every endpoint group.

TypeScript SDK

Use @usenotra/sdk for typed requests and responses on every endpoint, with retries, streaming and typed errors. The same package holds the AI traffic and web analytics tracking.

Quick start

Base URL:
Paths are versioned (/v1/..., and /v2/... for the Agent group). Requests authenticate with a bearer credential, which is either an API key from the dashboard or an OAuth access token from the Notra authorization server. Notra infers the organization from the credential, so the URL has no organization segment. Check that the API is reachable without a key:
Then make an authenticated request:

Create an API key

1

Open API Keys

In the dashboard, open API Keys at the bottom of the sidebar, which takes you to app.usenotra.com/{org-slug}/api-keys.
2

Click Create API Key

Pick a name, an expiration (no expiry, 7, 30, 60 or 90 days) and the permissions the key needs. Start from one of the presets (MCP Server, SDK, CLI) or choose Restricted to set read or write access per resource.
3

Copy the key

Keys start with ntra_ and the dashboard shows each key only once, so store the value in a server-side environment variable such as NOTRA_API_KEY.
API Keys in the Notra dashboard API Keys in the Notra dashboard Authentication covers scopes, presets and error responses.
Building a CLI, MCP client or agent that acts for a signed-in user? Use OAuth instead of a pasted key. Register a client, run the authorization code flow with PKCE (or the device flow on headless machines) and send the access token in the same Authorization: Bearer header, which the Notra MCP server also accepts. OAuth has the details.
Keep API keys private. If a key ends up in client-side code, anyone can use it to burn through your rate limits, even if the key is read-only, so make requests from your backend.

SDK installation

Create the client. It reads your key from NOTRA_API_KEY, or pass it as apiKey:
The SDK has one namespace per endpoint group: notra.discovery, notra.content, notra.webhooks, notra.schedules, notra.eventTriggers, notra.chats, notra.skills, notra.sites, notra.feedback, notra.geo and notra.agent. Each method is named after its operation’s operationId in this reference and takes one object: path and query parameters by name and the JSON body as body. Failed requests throw NotraAPIError with the status, code and recovery; rate limits and server errors are retried for you. Set environment: "sandbox" to use the sandbox with sample data. The source and the full guide are at github.com/usenotra/typescript-sdk.

API groups

Discovery

GET /v1/status is a public reachability check that also returns the authentication discovery metadata agents use to find out how to get a credential.

Content

Posts (list, get, update, delete, queue generation and poll its status), brand identities (list, generate, update, delete) and integrations (list, connect a GitHub repository, remove).

Schedules

Recurring content generation: list, create, update and delete schedules that turn repository activity into posts on a cadence.

Event triggers

Event-based generation fired by GitHub webhooks: list, create, get, update and delete triggers.

Chats

Start a chat and stream the reply, continue an existing chat, list chats or look a chat up by an external channel id.

Skills

Reusable writing skills, addressed by name: list, create, get, update and delete.

Feedback

AI agents post feedback to your public feedback URL without credentials, and you list, get and triage entries with an API key. Agent Feedback explains the setup.

GEO

Generative engine optimization per project: settings, tracked prompts and prompt sequences, competitors, scans, visibility reads (mention rates, timeseries, share of voice), content gaps and briefs, agent readiness, AI traffic and the traffic ingest token. Requires a GEO plan.

Agent

Durable agent sessions under /v2: start a session, send follow-up messages or answer input requests, stream session events and list sessions.

Responses and errors

Successful responses are JSON. List and detail responses in the Content and GEO groups also include an organization object (id, slug, name, logo) describing the organization the key belongs to. Errors are JSON with an error message, and authentication failures add a machine-readable code and a recovery hint:

Next steps

Authentication

API keys, OAuth, scopes and the exact error envelope.

Common tasks

Copy-paste examples for posts, generation jobs and GEO reads.

Pagination

Page through posts, feedback and scan history.

TypeScript types

Types and Zod schemas for the post endpoints.
Last modified on November 11, 2026