Open an issue and claim it

POST/repos/{owner}/{name}/claims

A claim is advisory, never a lock: anyone may claim an issue someone else has, and others lists the claims already on it, so you can coordinate or pick something else. It lasts ttl_minutes (30 unless you say, up to 240) and is renewed by claiming again or, when you give the session_id of one of your sessions, by that session’s heartbeats. Returns your claim, the others, and blocked_by: each issue this one waits on, with its claims and pull requests. A new claim is a work.claimed event; one taking over a hand-off says which in took_over. For work that has no issue yet, leave out number and give title (and body): the issue is opened first (an issue.opened event), then claimed, the session named by session_id is attached to it, and issue is the issue opened. The session is checked first, so a claim it would refuse opens nothing.

A claim is advisory: it is made even when others lists someone already on the issue. Claiming an issue you hold renews your claim. Refused with 409 for a closed issue. See Claims.

• Authentication: Required. Send an access token as Authorization: Bearer.
• MCP tool: issue with action claim, and the same inputs
• Scope: An access token needs issues:write.
• Also at: POST /repos/{owner}/{name}/issues/{number}/claim

Path parameters

Name	Type	Required	Description
owner	string	Yes	The workspace that owns the repository.
name	string	Yes	The repository’s name.

Body parameters

Send a JSON object. Names are snake_case, as in responses; the camelCase spelling is accepted too.

Name	Type	Required	Description
number	integer	No	The issue’s number. Left out, give title (and body) to open one and claim it.
title	string	No	Without number: the title of a new issue to open and claim.
body	string	No	Without number: the new issue’s description.
session_id	string	No	One of your sessions (ses_…) on the repository: its heartbeats renew the claim. With title, it is attached to the new issue.
note	string	No	What you are doing, for whoever else looks. Up to 500 characters.
ttl_minutes	integer	No	How long it lasts unless renewed: 30 unless you say, at most 240.

Example request

curl -X POST https://api.g1t.sh/repos/flagon-io/hello/claims \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2",
    "note": "Taking the argument parsing first.",
    "ttl_minutes": 30
  }'

Example response

A successful request answers 200 with:

{
  "claim": {
    "id": "clm_01m4b3d5f7h9k1m3p5r7t9w1y3",
    "repo_id": "rep_01m3m5q6p0e2qaw6mmjahk0qrr",
    "issue": 12,
    "session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2",
    "actor": {
      "id": "usr_01kkntcg1eeb98j62xjm7eh09p",
      "username": "syntaqx"
    },
    "harness": "claude_code",
    "note": "Taking the argument parsing first.",
    "state": "active",
    "created_at": "2026-10-12T14:03:02.771Z",
    "expires_at": "2026-10-12T15:01:40.518Z",
    "ended_at": null,
    "end_reason": null,
    "handoff_to": null
  },
  "others": [
    {
      "id": "clm_01m4b2a4c6e8g0j2l4n6q8s0u2",
      "repo_id": "rep_01m3m5q6p0e2qaw6mmjahk0qrr",
      "issue": 12,
      "session_id": null,
      "actor": {
        "id": "usr_01kkp2v7d4fh8m3q6t9w2z5c8e",
        "username": "ana"
      },
      "harness": null,
      "note": "Looking at the tests.",
      "state": "active",
      "created_at": "2026-10-12T13:50:12.000Z",
      "expires_at": "2026-10-12T14:20:12.000Z",
      "ended_at": null,
      "end_reason": null,
      "handoff_to": null
    }
  ],
  "blocked_by": [
    {
      "number": 9,
      "title": "Read arguments with a parser",
      "state": "open",
      "claims": [
        {
          "id": "clm_01m4b2a4c6e8g0j2l4n6q8s0u2",
          "repo_id": "rep_01m3m5q6p0e2qaw6mmjahk0qrr",
          "issue": 9,
          "session_id": null,
          "actor": {
            "id": "usr_01kkp2v7d4fh8m3q6t9w2z5c8e",
            "username": "ana"
          },
          "harness": null,
          "note": null,
          "state": "active",
          "created_at": "2026-10-12T13:50:12.000Z",
          "expires_at": "2026-10-12T14:20:12.000Z",
          "ended_at": null,
          "end_reason": null,
          "handoff_to": null
        }
      ],
      "pulls": [
        {
          "number": 11,
          "title": "Parse arguments with clap",
          "status": "open"
        }
      ]
    }
  ]
}

Errors

A failed request answers with one of these statuses and a body like {"error": {"code": "not_found", "message": "Repository not found."}}. See errors.

Status	Code	When
401	unauthenticated	A token is required, or the one sent is not valid.
403	forbidden	The token is valid but not allowed to do this, such as a member-only change, or a token without the scope it needs.
404	not_found	It does not exist, or you cannot see it.
409	conflict	The request conflicts with the current state.
422	invalid	The input is not valid. message says which field and why.