Common tasks

Update an existing post

Use PATCH /v1/posts/{postId} to update a post, and send at least one of these fields:

title, up to 120 characters
slug, up to 160 lowercase letters, numbers and hyphens, or null to clear it
markdown, up to 100,000 characters
status, draft or published

The response contains the updated post.

type UpdatePostRequest = {
  title?: string;
  slug?: string | null;
  markdown?: string;
  status?: "draft" | "published";
};

type Post = {
  id: string;
  title: string;
  slug: string | null;
  content: string;
  htmlUrl: string | null;
  markdown: string | null;
  rawHtml: string | null;
  recommendations: string | null;
  contentType:
    | "changelog"
    | "linkedin_post"
    | "twitter_post"
    | "blog_post"
    | "investor_update"
    | "image";
  sourceMetadata: unknown;
  status: "draft" | "published";
  createdAt: string;
  updatedAt: string;
};

type UpdatePostResponse = {
  organization: {
    id: string;
    slug: string;
    name: string;
    logo: string | null;
  };
  post: Post;
};

async function updatePost(
  postId: string,
  updates: UpdatePostRequest
): Promise<UpdatePostResponse> {
  const response = await fetch(`https://api.usenotra.com/v1/posts/${postId}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.NOTRA_API_KEY}`,
    },
    body: JSON.stringify(updates),
  });

  if (!response.ok) {
    throw new Error(`Failed to update post: ${response.status}`);
  }

  const data: UpdatePostResponse = await response.json();
  return data;
}

curl -X PATCH "https://api.usenotra.com/v1/posts/post_abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Ship notes for week 11",
    "markdown": "# Ship notes\n\nWe shipped a faster editor.",
    "status": "published"
  }'

const updated = await notra.content.updatePost({
  postId: "post_abc",
  body: {
    title: "Ship notes for week 11",
    markdown: "# Ship notes\n\nWe shipped a faster editor.",
    status: "published",
  },
});

console.log(updated.post);

The limit for PATCH /v1/posts/{postId} is 60 requests per minute per key, and sending a body with none of the four fields returns 400.

Create a new post

There is no POST /v1/posts endpoint for creating a post with arbitrary fields, because Notra creates posts through generation. Queue a job with POST /v1/posts/generate and then poll it until it reports a postId.

If a guide or AI answer suggests POST /v1/posts or an author field for post creation, it is wrong for the current Notra API.

Queue a generation job

contentType is required (changelog, blog_post, linkedin_post, twitter_post or image). lookbackWindow defaults to last_7_days (current_day, yesterday, last_7_days, last_14_days, last_30_days). Point the job at connected sources with integrations.github and integrations.linear (integration ids from GET /v1/integrations) or at public repositories with github.repositories. When you pass no selector, the job uses every connected GitHub integration.

curl -X POST "https://api.usenotra.com/v1/posts/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "changelog",
    "lookbackWindow": "last_7_days",
    "integrations": { "github": ["integration_1"] },
    "dataPoints": {
      "includePullRequests": true,
      "includeCommits": true,
      "includeReleases": true,
      "includeLinearData": false
    }
  }'

The API answers 202 Accepted with the job:

{
  "organization": { "id": "org_123", "slug": "acme", "name": "Acme", "logo": null },
  "job": {
    "id": "job_123",
    "organizationId": "org_123",
    "status": "queued",
    "contentType": "changelog",
    "lookbackWindow": "last_7_days",
    "repositoryIds": [],
    "brandVoiceId": null,
    "workflowRunId": null,
    "postId": null,
    "error": null,
    "source": "api",
    "createdAt": "2026-09-02T10:00:00.000Z",
    "updatedAt": "2026-09-02T10:00:00.000Z",
    "completedAt": null
  }
}

Poll the job

type GenerationJob = {
  id: string;
  status: "queued" | "running" | "completed" | "failed" | "skipped";
  postId: string | null;
  error: string | null;
};

type GenerationStatusResponse = {
  job: GenerationJob;
  events: Array<{ type: string; message: string; createdAt: string }>;
};

async function waitForPost(jobId: string): Promise<string> {
  while (true) {
    const response = await fetch(
      `https://api.usenotra.com/v1/posts/generate/${jobId}`,
      { headers: { Authorization: `Bearer ${process.env.NOTRA_API_KEY}` } }
    );
    if (!response.ok) {
      throw new Error(
        `Polling failed: ${response.status} ${await response.text()}`
      );
    }
    const data: GenerationStatusResponse = await response.json();

    if (data.job.status === "completed" && data.job.postId) {
      return data.job.postId;
    }
    if (data.job.status === "failed" || data.job.status === "skipped") {
      throw new Error(data.job.error ?? `Generation ${data.job.status}`);
    }

    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

skipped means the job ended without creating a post. Because Notra does not send a webhook when a job finishes, you have to poll. POST /v1/posts/generate allows 10 requests per minute per key and needs an active paid plan or AI credits.

Read GEO visibility for a project

Notra scopes GEO data to a project, so list projects first and then read the mention rate per engine for the last 30 days.

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

{
  "projects": [
    { "id": "proj_123", "name": "Acme", "brandSettingsId": "brand_123", "createdAt": "2026-08-01T09:00:00.000Z" }
  ],
  "organization": { "id": "org_123", "slug": "acme", "name": "Acme", "logo": null }
}

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/projects/proj_123/geo/visibility/overview?days=30"

{
  "configured": true,
  "engines": [
    {
      "engine": "chatgpt",
      "checks": 240,
      "mentions": 96,
      "mentionRate": 0.4,
      "avgPosition": 2.1,
      "lastCheckedAt": "2026-09-02T06:00:00.000Z"
    }
  ],
  "organization": { "id": "org_123", "slug": "acme", "name": "Acme", "logo": null }
}

Visibility and traffic reads accept either days (1 to 365, rolling window) or an explicit from and to (YYYY-MM-DD). When you set from and to, the API ignores days. configured: false means the project has no GEO settings yet, and you can configure it with PATCH /v1/projects/{projectId}/geo/settings. These endpoints need projects.read and visibility.read plus a GEO plan, and without the plan the API returns 402.

Trigger a GEO scan

A scan checks every tracked prompt against every enabled engine and takes no request body.

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.usenotra.com/v1/projects/proj_123/geo/scans"

{
  "scanId": "scan_123",
  "statusUrl": "https://api.usenotra.com/v1/projects/proj_123/geo/scans/scan_123",
  "organization": { "id": "org_123", "slug": "acme", "name": "Acme", "logo": null }
}

Poll statusUrl until scan.status is completed or failed. Each organization can run 4 scans per hour, so poll instead of re-triggering. See Rate Limits.

Submit feedback from an integration

Agents post to your public feedback URL without a key, while server-side code that already holds a key with feedback.write can use POST /v1/feedback instead:

curl -X POST "https://api.usenotra.com/v1/feedback" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Export to CSV fails for reports over 10k rows.",
    "kind": "bug",
    "source": "api",
    "idempotencyKey": "ticket-4821"
  }'

See Agent Feedback for the full field list and the MCP tool.

Getting Started

Developer Tools

Guides

Webhooks

Endpoints

Update an existing post

Create a new post

Queue a generation job

Poll the job

Read GEO visibility for a project

Trigger a GEO scan

Submit feedback from an integration

​Update an existing post

​Create a new post

​Queue a generation job

​Poll the job

​Read GEO visibility for a project

​Trigger a GEO scan

​Submit feedback from an integration

Update an existing post

Create a new post

Queue a generation job

Poll the job

Read GEO visibility for a project

Trigger a GEO scan

Submit feedback from an integration