Start a session

POST/repos/{owner}/{name}/sessions

harness is claude_code, codex, cursor, copilot or other. Give harness_session_id, the harness’s own id for the session, and starting again with it returns the session already started (refreshing the issue, pull request, branch, title and head given) instead of a new one, so a hook that fires twice is harmless. issue and pull attach it to an issue and a pull request of the repository; a pull request for an issue attaches that issue too. A subagent is a session of its own: give parent_id (one of your sessions here), its agent_type, the task and prompt its parent gave it, and as harness_session_id the parent’s harness id, /agent/ and the subagent’s id; it starts on the parent’s issue, pull request and branch unless it says otherwise, sees and is seen by its siblings in get_work and list_sessions, and once ended stays ended when started again. Returns the session (id ses_…, state active, idle or ended). A new session, or one started again after it ended, is a session.started event. Needs a confirmed email address and a role that may open issues.

Idempotent on harness_session_id: a second start with it returns this session, so call it from a hook without checking first. state is active, idle (no heartbeat for 15 minutes) or ended (ended, or no heartbeat for 2 hours: end_reason timed_out). A subagent gives parent_id, agent_type, task and prompt. See Sessions.

• Authentication: Required. Send an access token as Authorization: Bearer.
• MCP tool: session with action start, and the same inputs
• Scope: An access token needs pull_requests:write.

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 it works on.
pull	integer	No	The pull request it works on.
branch	string	No	The branch it works on.
title	string	No	What it is doing, in a few words. Up to 200 characters.
head_commit	string	No	The commit it is at, such as after a push.
harness	string	Yes	The harness the session runs in. One of claude_code, claude_managed_agents, codex, cursor, copilot, other.
harness_session_id	string	No	The harness’s own id for the session, such as Claude Code’s session_id; for a subagent, the parent’s, /agent/ and the subagent’s id. Starting again with it returns the same session.
parent_id	string	No	For a subagent: the session that started it (ses_…), one of yours on the repository.
agent_type	string	No	For a subagent: its kind, as the harness names it (Explore, security-reviewer).
task	string	No	For a subagent: the task it was given, in a few words. Up to 200 characters.
prompt	string	No	For a subagent: the prompt its parent gave it. Kept up to 4,000 characters.
model	string	No	The model it runs on, when known.

Example request

curl -X POST https://api.g1t.sh/repos/flagon-io/hello/sessions \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "harness": "claude_code",
    "harness_session_id": "5b0c1f9e-3d2a-4e8b-9f61-0c7d2a9e4b13",
    "issue": 12,
    "branch": "greet-caller",
    "title": "Make the greeting name the caller"
  }'

Example response

A successful request answers 200 with:

{
  "id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2",
  "repo_id": "rep_01m3m5q6p0e2qaw6mmjahk0qrr",
  "issue": 12,
  "pull": null,
  "branch": "greet-caller",
  "actor": {
    "id": "usr_01kkntcg1eeb98j62xjm7eh09p",
    "username": "syntaqx"
  },
  "harness": "claude_code",
  "harness_session_id": "5b0c1f9e-3d2a-4e8b-9f61-0c7d2a9e4b13",
  "title": "Make the greeting name the caller",
  "state": "active",
  "head_commit": null,
  "started_at": "2026-10-12T14:02:11.204Z",
  "last_seen_at": "2026-10-12T14:02:11.204Z",
  "ended_at": null,
  "end_reason": null
}

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.