---
title: "Open or resume an MCP-native repo-backed editing session for a saved source artifact when editing through Kody tools ..."
method: POST
path: "/v1/repo-sessions"
tags: ["repos"]
---

# Open or resume an MCP-native repo-backed editing session for a saved source artifact when editing through Kody tools ...

`POST /v1/repo-sessions`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/repo-sessions`
- Auth: HTTP bearer

Open or resume an MCP-native repo-backed editing session for a saved source artifact when editing through Kody tools instead of a local clone. Later repo capabilities can read, search, edit, validate, and publish against a mutable session branch. Pass conversation_id to resume that conversation's active session. Omitting conversation_id always mints a new session so concurrent callers of the same source do not share a workspace that has not checkpointed yet.

Org permission: `package:write`.

## Request body

- object
  - `source_id` string: Shared source id to open a session for. Prefer `target` when you know the saved package identity instead of the internal source id.
  - `target` union: User-facing repo-backed package identity. Use this instead of `source_id` when opening a saved package session.
    - object
      - `kind` 'package', required
      - `package_id` string, required: Saved-package UUID. Use when the scoped name is not known, or for a stable ref.
    - object
      - `kind` 'package', required
      - `kody_id` string, required: Package name (`@owner/leaf` or the name leaf). Prefer this when you know the name.
    - object
      - `kind` 'repo', required
      - `repo_id` string, required: Plain repo id to open or edit by stable identifier.
    - object
      - `kind` 'repo', required
      - `name` string, required: Plain repo name to open or edit by user-facing identity.
  - `conversation_id` string: Optional conversation id to associate with this repo session for default resolution in later calls.
  - `source_root` string: Optional repo subdirectory to treat as the working source root.
  - `default_branch` string: Optional default branch name hint for session creation.

## Response `200`

Success.

- object
  - `id` string, required
  - `source_id` string, required
  - `source_root` string, required
  - `base_commit` string, required
  - `session_branch` string, required
  - `source_branch` string, required
  - `conversation_id` string, nullable, required
  - `last_checkpoint_commit` string, nullable, required
  - `last_check_run_id` string, nullable, required
  - `last_check_tree_hash` string, nullable, required
  - `expires_at` string, nullable, required
  - `created_at` string, required
  - `updated_at` string, required
  - `published_commit` string, nullable, required
  - `manifest_path` string, required
  - `entity_type` 'package' | 'repo', required
  - `resolved_target` union, required
    - object
      - `kind` 'source', required
      - `source_id` string, required
      - `entity_kind` 'package' | 'repo', required
      - `entity_id` string, required
    - object
      - `kind` 'package', required
      - `source_id` string, required
      - `package_id` string, required
      - `kody_id` string, required
      - `name` string, required
    - object
      - `kind` 'repo', required
      - `source_id` string, required
      - `repo_id` string, required
      - `name` string, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)