Common Tasks

Update an existing post

Use PATCH /v1/posts/{postId} to update a post. Send at least one of title (up to 120 characters), slug (lowercase letters, numbers and hyphens, up to 160 characters, or null to clear it), markdown (up to 100,000 characters) or 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);

PATCH /v1/posts/{postId} is limited to 60 requests per minute per key. 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. Posts are created by generation: queue a job with POST /v1/posts/generate, 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, that information is not correct 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 no selector is given, every connected GitHub integration is used.

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. Notra does not send a webhook when a job finishes, so polling is the way to find out. POST /v1/posts/generate is limited to 10 requests per minute per key and needs an active paid plan or AI credits.

Read GEO visibility for a project

GEO data is scoped to a project. List projects first, 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 from/to are set, days is ignored. configured: false means the project has no GEO settings yet; configure it with PATCH /v1/projects/{projectId}/geo/settings. These endpoints need projects.read and visibility.read plus a GEO plan. Without the plan the API returns 402.

Trigger a GEO scan

A scan checks every tracked prompt against every enabled engine. It 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. Scans are limited to 4 per hour per organization, so poll rather than re-trigger. See Rate Limits.

Submit feedback from an integration

Agents post to your public feedback URL without a key. 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

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