Getting started

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 across the Content, Schedules, Event Triggers, Chats, Skills, Feedback and Agent endpoints.

Quick start

Base URL:

https://api.usenotra.com

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:

curl https://api.usenotra.com/v1/status

{
  "status": "ok",
  "service": "Notra API",
  "version": "1.0.0",
  "public": true,
  "authentication": {
    "type": "bearer",
    "resource_metadata": "https://api.usenotra.com/.well-known/oauth-protected-resource",
    "guide": "https://www.usenotra.com/auth.md"
  }
}

Then make an authenticated request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/posts"

const response = await fetch("https://api.usenotra.com/v1/posts", {
  headers: {
    Authorization: `Bearer ${process.env.NOTRA_API_KEY}`,
  },
});

const data = await response.json();
console.log(data.posts);

import { Notra } from "@usenotra/sdk";

const notra = new Notra({
  bearerAuth: process.env.NOTRA_API_KEY ?? "",
});

const result = await notra.content.listPosts();

console.log(result.posts);

Create an API key

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.

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.

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.

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

npm install @usenotra/sdk

yarn add @usenotra/sdk

pnpm add @usenotra/sdk

bun add @usenotra/sdk

Initialize the client with your API key:

import { Notra } from "@usenotra/sdk";

const notra = new Notra({
  bearerAuth: process.env.NOTRA_API_KEY ?? "",
});

const post = await notra.content.getPost({ postId: "post_abc" });

The SDK exposes one namespace per endpoint group: notra.content, notra.schedules, notra.eventTriggers, notra.chats, notra.skills, notra.feedback and notra.agent. Notra generates it from the OpenAPI document and publishes it at github.com/usenotra/typescript-sdk.

GEO endpoints (projects, prompts, competitors, scans, visibility, gaps, briefs, agent readiness, traffic) are not in the SDK yet. Call them with fetch or generate a client from the OpenAPI document.

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:

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "recovery": "Send Authorization: Bearer <NOTRA_API_KEY>. See https://www.usenotra.com/auth.md for agent credential discovery."
}

Status	When
`400`	Validation failed. `error` names the field, for example `limit: Too big: expected number to be <=100`.
`401`	Missing, invalid or expired credential (API key or OAuth token). The response also carries a `WWW-Authenticate` header with the OAuth discovery URL.
`402`	The organization has no active paid plan or AI credits for a write, or no GEO plan for a GEO endpoint.
`403`	The key lacks the scope the endpoint needs.
`404`	Resource not found, or an unknown route.
`409`	Conflict, for example a duplicate name.
`429`	Rate limited. See Rate Limits.
`503`	The authentication or billing service is temporarily unavailable. Retry with backoff.

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.

Developer Tools

Guides

Webhooks

Endpoints

Getting started

REST API

TypeScript SDK

Quick start

Create an API key

SDK installation

API groups

Discovery

Content

Schedules

Event triggers

Chats

Skills

Feedback

GEO

Agent

Responses and errors

Next steps

Authentication

Common tasks

Pagination

TypeScript types

REST API

TypeScript SDK

​Quick start

​Create an API key

​SDK installation

​API groups

Discovery

Content

Schedules

Event triggers

Chats

Skills

Feedback

GEO

Agent

​Responses and errors

​Next steps

Authentication

Common tasks

Pagination

TypeScript types

Quick start

Create an API key

SDK installation

API groups

Responses and errors

Next steps