---
title: "Claim a content gap or brief before writing it"
method: POST
path: "/v1/projects/{projectId}/geo/claims"
tags: ["GEO"]
---

# Claim a content gap or brief before writing it

`POST /v1/projects/{projectId}/geo/claims`

## Request

- Base URL: `https://api.usenotra.com`
- URL: `https://api.usenotra.com/v1/projects/{projectId}/geo/claims`
- Auth: HTTP bearer

Call this before your own agent writes the article for a content gap or brief, so Notra's writer, Autopilot and other agents do not write it at the same time. Returns 409 while someone else holds the claim. Claiming again with the same credentials renews it. The claim lapses after `ttlMinutes`. Saving the brief's draft post with updatePost releases it; otherwise call releaseGeoContentClaim, or reportGeoContentAgentFailure when the agent cannot finish. A brief planned from a gap shares the gap's claim. While it is held, the dashboard shows the gap as being written by `agent`.

## Path parameters

- `projectId` string, required

## Request body

- ClaimGeoContentRequest
  - `briefId` string: Brief to claim. A brief planned from a gap shares that gap's claim.
  - `sourceKind` 'gap' | 'prompt' | 'search_console' | 'ai_search': Kind of gap: gap for a row in promptGaps, search_console for searchGaps, ai_search for aiSearchGaps, prompt for a tracked prompt.
  - `sourceId` string: The gap's id from listGeoContentGaps. Send with sourceKind instead of briefId.
  - `agent` string, required: Name shown in Notra while the claim is held, for example "Claude Code".
  - `ttlMinutes` integer: Minutes until the claim lapses. Defaults to 30. Claim again with the same credentials to renew it.

## Response `200`

Claim taken or renewed

- ClaimGeoContentResponse
  - `sourceKind` 'manual' | 'gap' | 'prompt' | 'search_console' | 'ai_search', required: Kind of the claimed item. manual means a brief that was not planned from a gap.
  - `sourceId` string, required: Gap id, or the brief id when sourceKind is manual.
  - `agent` string, required: Agent holding the claim.
  - `expiresAt` string, required: ISO timestamp when the claim lapses unless renewed.
  - `organization` object, required: Workspace the request ran in.
    - `id` string, required: Workspace ID. Account API keys can send it, or the slug, as X-Notra-Organization-Id.
    - `slug` string, required: URL-safe workspace handle, unique across Notra.
    - `name` string, required: Workspace display name.
    - `logo` string, nullable, required: Workspace logo image URL. Null when none is set.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `402`: GEO plan or available AI credits required
- `403`: Forbidden
- `404`: Organization, project or resource not found
- `409`: Another agent holds the claim
- `500`: Internal server error
- `503`: Authentication or billing service unavailable

## Changes

- **2026-11-21** `9c3a3acdf9f7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/usenotra/apis/notra-api/changes/v1/projects/:projectId/geo/claims/post.md)

---

[API](https://skmtc.dev/usenotra/apis/notra-api.md) - [All operations](https://skmtc.dev/usenotra/apis/notra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usenotra/apis/notra-api/revisions/9c3a3acdf9f7?raw)
