# Start an agent session on an issue

> Start work on an issue in a session of its own, on the person's own Claude: g1t runs no model and bills nothing for it.

<div class="g1t-endpoint"><span class="g1t-method" data-method="post">POST</span><code>/repos/{owner}/{name}/agent-sessions</code></div>

Give `issue`, or `title` and `body` to open a new issue first; `instruction` adds to what the session is asked; `mode` (plan, implement or review) says what kind of work it is. With the workspace's Anthropic connection (an owner adds it under Integrations), g1t starts a Claude Managed Agents session with that key: g1t's MCP server attached with a credential for you and this repository only that lasts the session and is kept in a vault on the Anthropic account (never in the prompt), g1t's skills (work-on-issue, coordinate, fix-integration) next to the account's own, and the session, its subagents (threads), what they touched and what they reported recorded here as a g1t session (`harness` claude_managed_agents). Returns `session`, its `session_url` on g1t, `provider_session_url`, and `prompt`. With `handoff` true, or without an Anthropic connection when `handoff` is not false, nothing is started: `command` is a Claude Code command line, and `prompt` what to paste, for someone with g1t's Claude Code plugin, whose session then attaches to the issue as it starts.

Runs on the workspace's own Anthropic key: g1t runs no model and bills nothing for it. Without an Anthropic connection (or with `handoff: true`) nothing is started and `command` is a Claude Code command line to run with g1t's plugin. See [Sessions](/guides/sessions/#start-a-session-on-your-anthropic-account).

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`session`](/reference/mcp/#session) with `action` `dispatch`, and the same inputs
- **Scope:** An access token needs [`pull_requests:write`](/guides/authentication/#scopes).

## 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 |
| --- | --- | --- | --- |
| `issue` | integer | No | The issue to work on. Left out, give title (and body) to open one. |
| `title` | string | No | Without issue: the title of a new issue to open and work on. |
| `body` | string | No | Without issue: the new issue's description. |
| `instruction` | string | No | What to do beyond what the issue says. Up to 4,000 characters. |
| `mode` | string | No | What kind of work: plan (say how, change nothing), implement (the default) or review (review its pull request). One of `plan`, `implement`, `review`. |
| `handoff` | boolean | No | true for a Claude Code command and prompt to run yourself instead of a session on the workspace's Anthropic account; false to refuse when there is no Anthropic connection. Left out, a session when the workspace can, else the hand-off. |

## Example request

```sh
curl -X POST https://api.g1t.sh/repos/flagon-io/hello/agent-sessions \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": 12,
    "mode": "implement",
    "instruction": "Keep the old greeting behind a flag."
  }'
```

## Example response

A successful request answers `200` with:

```json
{
  "issue": 12,
  "session": {
    "id": "ses_01m4c9a8b7c6d5e4f3g2h1j0k9",
    "repo_id": "rep_01m3m5q6p0e2qaw6mmjahk0qrr",
    "issue": 12,
    "pull": null,
    "branch": null,
    "actor": {
      "id": "usr_01kkntcg1eeb98j62xjm7eh09p",
      "username": "syntaqx"
    },
    "harness": "claude_managed_agents",
    "harness_session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
    "title": "#12 Make the greeting name the caller",
    "state": "active",
    "head_commit": null,
    "started_at": "2026-10-12T15:10:02.117Z",
    "last_seen_at": "2026-10-12T15:10:02.117Z",
    "ended_at": null,
    "end_reason": null,
    "parent_id": null,
    "agent_type": null,
    "task": null,
    "prompt": null,
    "result": null,
    "model": "claude-opus-5-5",
    "subagents": 0
  },
  "session_url": "https://g1t.sh/syntaqx/hello/work/sessions/ses_01m4c9a8b7c6d5e4f3g2h1j0k9",
  "provider": "anthropic",
  "provider_session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "provider_session_url": "https://platform.claude.com/workspaces/default/sessions/sesn_011CZkZAtmR3yMPDzynEDxu7",
  "handoff": false,
  "command": null,
  "prompt": "Work on issue #12 in syntaqx/hello: Make the greeting name the caller.\n\n…"
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#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. |