API & Protocol Reference

How to read this page

This page is organized by real caller surface — health, Forge Jira App access, launch-code exchange, task permits, telemetry, and project indexes — instead of by raw implementation tags.

Contract guide, not stricter than the contract

The published OpenAPI document intentionally leaves several request and response bodies as generic objects. Where that happens, the examples below show the stable first-party payload shape used by the Jira App and IDE clients rather than pretending the schema is tighter than the published protocol.

24 documented route-method combinations

Health, Forge Jira App access, launch-code exchange, task permits, telemetry, and project-index surfaces are grouped below by how they are actually used.

Machine schema at /openapi.json

The backend also serves Swagger UI at /docs, while this page explains the contract in first-party terms and highlights what is deprecated or disabled in the live codebase.

Forge + launch-code + permit flow

The modern path is Forge-authenticated Jira App access, a strictly single-use Jira request key, a one-time launch code, and a short-lived task permit inside the IDE.

Authentication surfaces

The current codebase uses Forge bearer auth plus rotating Jira request keys for Jira-side calls, and a one-time launch-code exchange before the IDE receives its task permit.

Prefer the modern path for net-new integrations

The published protocol still includes signed public and instance-key bridge routes for compatibility. New Jira App integrations should prefer Forge-authenticated routes, one-time launch codes, and task permits.

Forge + rotating Jira request keys

The Jira App authenticates with a Forge bearer token rather than a stored local backend key.
The first Jira-side backend call is POST /v1/jira/request-key, which returns the current single-use request key.
The server accepts each Jira request key exactly once, keeps it short-lived, binds it to the same tenant/session context, and rejects replays.
Each successful Jira App backend response rotates X-SeeCodes-Next-Request-Key, invalidates the previous key, and resolves concurrent races so only one request can consume a given key.

One-time launch codes

POST /v1/security/vscode-link returns a one-time launch code plus vscode:// and HTTPS launcher URLs.
The browser-facing launch link carries only the launch code, never the reusable task permit.
POST /v1/security/launch-exchange rejects unless the code is unused and its bound projectId/taskId exactly match the exchange request.

Task-scoped permits

The exchanged task permit is the bearer credential used on /v1/tasks/* and /v1/projects/*/indexes/*.
The permit is bound to one Jira project/task pair, and the server rejects task, run, and project-index requests outside that exact binding.
The current backend issues a fresh 24-hour permit after launch-code exchange or direct task-permit minting.

Current request-key and permit headers

POST /v1/jira/request-key
Authorization: Bearer <forge-invocation-token>

GET /v1/instances/me
Authorization: Bearer <forge-invocation-token>
X-SeeCodes-Jira-Request-Key: <single-use request key>

X-SeeCodes-Next-Request-Key: <rotate this into the next Jira App request>
Authorization: Bearer <task-permit>

Common integration flows

These are the first-party flows the current Jira App and IDE extensions actually use day to day.

Jira App backend request-key handshake

POST /v1/jira/request-key with a Forge bearer token.
Call a Jira App backend route such as GET /v1/instances/me with X-SeeCodes-Jira-Request-Key.
On success, the server consumes that key, rejects later replays, and returns X-SeeCodes-Next-Request-Key.
Rotate immediately to the new current key on the next Jira App backend request; concurrent replays of the old key lose.

Secure Jira-to-IDE launch

POST /v1/security/vscode-link returns a one-time launch code plus vscode:// and HTTPS launcher URLs.
The browser opens /v1/launch or the vscode:// URI with the launch code only.
The extension calls POST /v1/security/launch-exchange to swap the one-time code for the real task permit; the backend rejects the exchange unless projectId/taskId exactly match the code binding.
The extension then calls GET /v1/tasks/context to hydrate Jira task context and any initial editor payload.

Run and inspect task work

POST /v1/tasks/init creates the run and returns presigned upload targets such as list.md.
POST /v1/tasks/{runId}/start queues execution after the uploads complete.
GET /v1/tasks/{runId} is polled until the run settles.
GET /v1/tasks/{runId}/output and GET /v1/tasks/{runId}/logs fetch the final artifacts.

Sync progress and retrospectives

POST /v1/tasks/{taskId}/progress stores the issue-level ready / left / risk document.
POST /v1/tasks/activity-snapshot records short activity windows for retrospective scoring.
GET /v1/jira/usage and GET /v1/jira/team-competition power the Jira-side analytics and retrospective views.
POST /v1/jira/instance-metrics lets the Jira App report installation-level counts such as installed users.

Tag: system

Health and schema

Low-level routes used for liveness checks and machine-readable API discovery.

GET/healthz

Health check

Minimal liveness probe used by deployment verification and monitoring.

Response shape

{
  "ok": true
}

Notes

This is the lightweight route most smoke tests and health checks should probe first.

GET/openapi.json

OpenAPI schema

Returns the machine-readable OpenAPI document used by client generators and the built-in Swagger UI.

Response shape

application/json
- OpenAPI document for the current public surface

Notes

Swagger UI is served separately at /docs.

Tags: security + instances + tasks

Forge installation access, launch security, and task context

Routes used by the Jira App to inspect installation state, rotate the single-use Jira request key, mint launch payloads, exchange launch codes, and hydrate the task workspace.

POST/v1/jira/request-key

Issue a single-use Jira backend request key

Bootstraps the single-use request-key rotation used by Forge-authenticated Jira App backend calls.

Access pattern

Forge bearer token from the Jira App.

Typical request body

{
}

Response shape

{
  "ok": true,
  "requestKey": "sc_jira_req_...",
  "expiresAt": 1735689600
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The current implementation accepts an optional body but does not rely on it for authentication.
The server accepts a Jira request key exactly once.
The server rejects a Jira App request unless the presented request key is the current unexpired key bound to the same tenant/session context.
On successful use, the server atomically consumes the current request key, returns X-SeeCodes-Next-Request-Key, invalidates the previous key, and handles concurrent races safely so only one request can consume that key.
Subsequent Jira App backend calls send X-SeeCodes-Jira-Request-Key and read X-SeeCodes-Next-Request-Key from the response.

GET/v1/instances/me

Read installation state

Returns the backend view of the current Jira installation after Forge auth and request-key validation.

Access pattern

Forge bearer token plus X-SeeCodes-Jira-Request-Key. The server rejects the request unless that key is the current unexpired single-use key bound to the same tenant/session context. Optional cloudIdHint and siteUrlHint values help the backend resolve the correct installation.

Parameters

cloudIdHint (optional string or null)
siteUrlHint (optional string or null)

Response shape

{
  "ok": true,
  "cloudId": "ari:cloud:ecosystem::installation/...",
  "status": "active",
  "credits": 42,
  "apiKeyPrefix": "av_inst_...",
  "updatedAt": 1710000000,
  "installationId": "ari:cloud:ecosystem::installation/...",
  "capabilitySet": "capabilityadvanced",
  "licenseActive": true,
  "activationSource": "forge-license",
  "devModeActive": false,
  "billingMode": "forge",
  "siteUrl": "https://tenant.atlassian.net"
}

Notes

The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
This is the primary installation-health route used by the Jira App settings and dashboard surfaces.

POST/v1/security/vscode-link

Mint a secure IDE launch payload

Generates the one-time launch code and launcher URLs used to open a Jira task in VS Code or Cursor.

Access pattern

Typical request body

{
  "projectId": "AUTH",
  "taskId": "AUTH-128",
  "userAccountId": "557058:abcd...",
  "cloudIdHint": "optional",
  "siteUrlHint": "https://tenant.atlassian.net",
  "expirationDays": 14,
  "jiraContext": { "...": "optional task context" },
  "initialTaiDoc": { "...": "optional editor boot state" }
}

Response shape

{
  "ok": true,
  "launchCode": "sc_launch_...",
  "vscodeUrl": "vscode://eprojac.seecodes-task-runner/project/AUTH/task/AUTH-128?code=sc_launch_...",
  "httpsUrl": "https://dev.seecodes.com/v1/launch?p=AUTH&t=AUTH-128&c=sc_launch_...",
  "expiresAt": 1735689600
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The minted launch code or task permit is bound to the exact projectId and taskId in the request. Later task and project routes enforce that binding as a hard server-side invariant.
The launcher payload intentionally returns launchCode rather than the reusable task permit.
The browser-facing launch link lifetime is currently configurable from 1 to 14 days in Jira App settings.

POST/v1/security/task-permit

Mint a task-scoped permit directly

Generates the bearer permit for a specific Jira task without going through the browser launcher flow.

Access pattern

Typical request body

{
  "projectId": "AUTH",
  "taskId": "AUTH-128",
  "userAccountId": "557058:abcd...",
  "cloudIdHint": "optional",
  "siteUrlHint": "https://tenant.atlassian.net"
}

Response shape

{
  "ok": true,
  "cloudId": "ari:cloud:ecosystem::installation/...",
  "projectId": "AUTH",
  "taskId": "AUTH-128",
  "permit": "eyJhbGciOi...",
  "expiresAt": 1735689600
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The minted launch code or task permit is bound to the exact projectId and taskId in the request. Later task and project routes enforce that binding as a hard server-side invariant.
This direct permit-minting route is what Jira-side background flows use when they need task-scoped backend access without launching the IDE.

POST/v1/security/launch-exchange

Exchange a one-time launch code for the task permit

Consumes the browser-facing one-time launch code and returns the real task-scoped bearer permit used by the IDE.

Access pattern

The one-time launch code in the request body is the credential.

Typical request body

{
  "code": "sc_launch_...",
  "projectId": "AUTH",
  "taskId": "AUTH-128"
}

Response shape

{
  "ok": true,
  "cloudId": "ari:cloud:ecosystem::installation/...",
  "projectId": "AUTH",
  "taskId": "AUTH-128",
  "permit": "eyJhbGciOi...",
  "expiresAt": 1735689600
}

Notes

First-party extensions exchange the launch code as soon as the IDE opens.
The launch code is single-use and the server rejects every replay after the first successful exchange.
The server rejects launch exchange unless the code is unused, unexpired, and the supplied projectId and taskId exactly match the values bound when the code was minted.

GET/v1/tasks/context

Read stored task context

Returns the stored Jira task context and optional initial editor payload for the permit’s project/task pair.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Response shape

{
  "ok": true,
  "context": {
    "title": "Implement auth flow",
    "descriptionMd": "...",
    "attachments": [],
    "images": []
  },
  "initialTai": {
    "version": 1,
    "task": { "...": "..." }
  }
}

Notes

The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The server resolves task context only for the exact projectId/taskId pair bound into the presented permit.
Returns { ok: false, error: "Context not found" } when no Jira-side context was persisted with the task.

GET/v1/launch

HTTPS launcher for vscode:// fallback

Small HTML launcher page that redirects into the vscode:// protocol while preserving optional backend-route and language hints.

Parameters

p (required string) — projectId
t (required string) — taskId
c (required string) — one-time launch code
baseUrl (optional string or null) — backend route hint preserved through the launcher
statusLanguage (optional string or null) — task-status language preserved through the launcher

Response shape

text/html
- lightweight launcher page
- redirects into vscode://... using the one-time launch code

Notes

The current launcher contract uses c for the one-time launch code.
The older k query parameter is no longer part of the current public launcher flow.

Tags: tasks

Task lifecycle, progress, and activity snapshots

Permit-scoped routes for storing issue progress, creating runs, polling AI execution, and recording retrospective activity windows.

POST/v1/tasks/{taskId}/progress

Save task progress

Stores structured issue-level progress such as ready items, remaining work, confidence, and risk flags.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Typical request body

{
  "ready": ["Protected-route wrapper is live"],
  "left": ["Callback validation still needs coverage"],
  "progress": "67%",
  "confidence": "Medium",
  "risks": ["Identity provider payload may still change"],
  "logs": ["Recent activity summary line"]
}

Response shape

{
  "ok": true
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The server rejects requests unless the path taskId exactly matches the permit's bound taskId.
This is the structured state later surfaced in Jira issue panels, the AI Readiness field, and the AI Progress Report field.

GET/v1/tasks/{taskId}/progress

Read task progress

Returns the stored progress document for a Jira issue.

Access pattern

Task permit, or Forge bearer token plus X-SeeCodes-Jira-Request-Key when the Jira App is the caller. When a task permit is used, the server still enforces the exact projectId/taskId binding carried by that permit.

Parameters

projectId (required string)
cloudIdHint (optional string or null)

Response shape

{
  "ok": true,
  "progress": {
    "updatedAt": "2026-04-04T12:34:56Z",
    "ready": ["Protected-route wrapper is live"],
    "left": ["Callback validation still needs coverage"],
    "progress": "67%",
    "confidence": "Medium",
    "risks": ["Identity provider payload may still change"],
    "logs": ["Recent activity summary line"]
  }
}

Notes

The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
When this route is called with a task permit, the server rejects requests unless query projectId exactly matches the permit's bound projectId and path taskId exactly matches the permit's bound taskId.
The Jira App issue panel, the custom fields, and the extension all read the same structured progress document.

POST/v1/tasks/init

Initialize an AI run

Creates a runId and returns presigned upload targets for the task input files.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Typical request body

{
  "model": "strict light",
  "files": ["list.md"]
}

Response shape

{
  "ok": true,
  "runId": "run_abc123",
  "bucket": "task-bucket-name",
  "prefix": "tmp/...",
  "uploads": {
    "list.md": "https://presigned-upload-url"
  }
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The created run is bound to the exact projectId/taskId pair carried by the presented permit. Later /v1/tasks/{runId}* routes reject requests outside that binding.
The files array defaults to ["list.md"] when omitted by first-party callers.

POST/v1/tasks/{runId}/start

Queue the AI run

Starts execution for a previously initialized run after the required uploads complete.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Typical request body

{
  "model": "strict light",
  "userPrompt": "generate change log"
}

Response shape

{
  "ok": true,
  "runId": "run_abc123",
  "status": "queued",
  "estimatedInputTokens": 12456,
  "estimatedCredits": 37
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The server rejects requests unless the path runId resolves to the same projectId/taskId pair bound into the presented permit.

GET/v1/tasks/{runId}

Poll run status

Returns the current status document for a run.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Response shape

{
  "ok": true,
  "status": {
    "status": "queued | in_process | processing_remote | succeeded | failed",
    "updatedAt": "2026-04-04T12:34:56Z",
    "error": "optional",
    "resultZipUrl": "optional"
  }
}

Notes

The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The server rejects requests unless the path runId resolves to the same projectId/taskId pair bound into the presented permit.
First-party clients poll this route until the run settles.

GET/v1/tasks/{runId}/output

Read task output

Returns the final text artifact produced by a successful AI run.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Response shape

text/plain
- raw output artifact
- commonly markdown or other structured text depending on the prompt

Notes

The server rejects requests unless the path runId resolves to the same projectId/taskId pair bound into the presented permit.
The published OpenAPI document leaves the schema open-ended; first-party clients treat this as plain text.

GET/v1/tasks/{runId}/logs

Read task logs

Returns the plain-text execution log for a run.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Response shape

text/plain
- raw execution log artifact for the run

Notes

The server rejects requests unless the path runId resolves to the same projectId/taskId pair bound into the presented permit.
Useful when a run fails or needs post-run investigation.

POST/v1/tasks/activity-snapshot

Save task activity snapshot

Persists a short activity window with active-time, diff-size, and semantic change signals for retrospective scoring.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Typical request body

{
  "windowStartedAt": "2026-04-04T10:00:00.000Z",
  "windowEndedAt": "2026-04-04T10:15:00.000Z",
  "taskStartedAt": "2026-04-04T08:30:00.000Z",
  "taskAgeMinutes": 105,
  "humanActiveMs": 420000,
  "locAdded": 28,
  "locRemoved": 11,
  "locTotal": 39,
  "changedFiles": ["src/auth.ts", "src/routes.tsx"],
  "changedFilesCount": 2,
  "architectureChange": false,
  "logicChange": true,
  "specificationUiChange": false
}

Response shape

{
  "ok": true,
  "stored": true,
  "timestamp": "2026-04-04T10:15:00.000000Z",
  "effortUnits": 91
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The server stores the snapshot only against the exact projectId/taskId pair bound into the presented permit and rejects cross-task writes.
This route feeds the Team Competition retrospective board instead of the issue-level progress field.

Tags: telemetry

Telemetry, analytics, and retrospectives

Forge-authenticated routes that power the Jira usage dashboard, installation metrics, disabled telemetry ingestion stub, and the retrospective competition board.

GET/v1/jira/usage

Read Jira usage analytics

Returns recent usage rows plus the backend’s current availableCredits value for the installation.

Access pattern

Forge bearer token plus X-SeeCodes-Jira-Request-Key. The server rejects the request unless that key is the current unexpired single-use key bound to the same tenant/session context.

Parameters

cloudIdHint (optional string or null)

Response shape

{
  "ok": true,
  "items": [
    {
      "timestamp": "2026-04-04T12:34:56Z",
      "type": "task_run",
      "taskId": "AUTH-128",
      "credits": 5
    }
  ],
  "availableCredits": 42
}

Notes

The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
Used by the Jira AI Requests Analytics dashboard.

POST/v1/jira/instance-metrics

Report installation metrics

Lets the Jira App report installation-level metrics such as installed user counts.

Access pattern

Forge bearer token plus X-SeeCodes-Jira-Request-Key. The server rejects the request unless that key is the current unexpired single-use key bound to the same tenant/session context.

Typical request body

{
  "installedUsersCount": 17,
  "source": "forge-hourly-sync"
}

Response shape

{
  "ok": true
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.

POST/v1/jira/telemetry/events

Ingest telemetry events (currently disabled)

Direct editor-side telemetry ingestion route that is intentionally disabled in the current live codebase.

Access pattern

Published schema route; the live codebase currently responds with an authenticated-ingestion deprecation error.

Typical request body

{
  "events": [
    {
      "eventType": "ai.usage",
      "cloudId": "ari:cloud:ecosystem::installation/...",
      "requestId": "1f0d7e2e-...",
      "timestamp": "2026-04-04T12:34:56Z"
    }
  ]
}

Response shape

{
  "detail": "Direct VS Code telemetry ingestion is disabled until an authenticated sender contract with replay protection and rate limits is finalized."
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The extension-side sender exists in code, but the backend keeps this route disabled until the authenticated sender contract is finalized.

GET/v1/jira/team-competition

Read team competition data

Returns scoped telemetry items, task summaries, the current monthly baseline, and formula metadata for the retrospective board.

Access pattern

Parameters

projectId (optional string or null)
startDate (optional string or null)
endDate (optional string or null)
cloudIdHint (optional string or null)
siteUrlHint (optional string or null)

Response shape

{
  "ok": true,
  "items": [...],
  "taskSummaries": [...],
  "monthBaseline": {
    "month": "2026-04",
    "taskCount": 18,
    "medianEffortUnits": 72
  },
  "formula": {
    "version": "v1",
    "weights": {
      "activeMinute": 1.8,
      "locChanged": 0.18,
      "changedFile": 3,
      "architectureBonus": 24,
      "logicBonus": 14,
      "specificationUiBonus": 10
    }
  },
  "sourceSummary": {
    "snapshotItems": 124,
    "taskRunFallbackItems": 12,
    "vscodeFallbackItems": 5,
    "fallbackTaskCount": 7
  }
}

Notes

The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
This route is paired with POST /v1/tasks/activity-snapshot, which is how IDE activity reaches the retrospective board.

Tags: models + tasks

Model catalog and project indexes

Helper routes used by editor-side surfaces to discover available model aliases and to reuse previously generated explainer/index entries.

GET/v1/models

Read the model catalog

Returns the current model aliases, context limits, descriptions, and pricing metadata exposed by the backend.

Response shape

{
  "ok": true,
  "models": [
    {
      "id": "strict light",
      "name": "strict light",
      "maxContext": 100000,
      "description": "Fast, high-context strict tasks",
      "pricing": {
        "base": 12.5,
        "per_token": 0.0006
      }
    }
  ]
}

Notes

The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
Used by IDE and Jira surfaces that need model pickers or context-limit hints.

POST/v1/projects/{projectId}/indexes/query

Query reusable project index entries

Looks up path/hash pairs against the stored project index and returns same-path or hash-reused matches.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Typical request body

{
  "items": [
    {
      "path": "src/auth.ts",
      "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

Response shape

{
  "ok": true,
  "updatedAt": 1710000000000,
  "matches": {
    "src/auth.ts": {
      "pathMatched": true,
      "hashMatchedPath": "src/auth.ts",
      "entry": {
        "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "updatedAt": 1710000000000,
        "short": "Authentication helper",
        "detailed": "Longer explainer...",
        "important_symbols": ["AuthGuard"]
      }
    }
  }
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The server rejects requests unless the path projectId exactly matches the permit's bound projectId.

POST/v1/projects/{projectId}/indexes/upsert

Upsert reusable project index entries

Writes or updates index entries and optionally deletes paths that should be removed from the remote index.

Access pattern

Task permit via Authorization: Bearer <task-permit>. The server rejects task, run, and project-index requests unless they resolve to the exact projectId/taskId pair bound into that permit.

Typical request body

{
  "entries": {
    "src/auth.ts": {
      "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "updatedAt": 1710000000000,
      "short": "Authentication helper",
      "detailed": "Longer explainer...",
      "important_symbols": ["AuthGuard"],
      "dependencies": ["src/session.ts"],
      "exports": ["AuthGuard"]
    }
  },
  "deletePaths": ["src/old-auth.ts"]
}

Response shape

{
  "ok": true,
  "updatedAt": 1710000000000,
  "upserted": 1,
  "deleted": 1,
  "totalFiles": 340
}

Notes

The published OpenAPI schema intentionally leaves this body open-ended; the example below shows the stable first-party payload shape.
The published OpenAPI schema intentionally leaves this response open-ended; the example below shows the stable first-party envelope.
The server rejects requests unless the path projectId exactly matches the permit's bound projectId.

SeeCodes Execution Engine protocol

How to read this page

24 documented route-method combinations

Machine schema at /openapi.json

Forge + launch-code + permit flow

Authentication surfaces

Forge + rotating Jira request keys

One-time launch codes

Task-scoped permits

Common integration flows

Jira App backend request-key handshake

Secure Jira-to-IDE launch

Run and inspect task work

Sync progress and retrospectives

Health and schema

Health check

OpenAPI schema

Forge installation access, launch security, and task context

Issue a single-use Jira backend request key

Read installation state

Mint a secure IDE launch payload

Mint a task-scoped permit directly

Exchange a one-time launch code for the task permit

Read stored task context

HTTPS launcher for vscode:// fallback

Task lifecycle, progress, and activity snapshots

Save task progress

Read task progress

Initialize an AI run

Queue the AI run

Poll run status

Read task output

Read task logs

Save task activity snapshot

Telemetry, analytics, and retrospectives

Read Jira usage analytics

Report installation metrics

Ingest telemetry events (currently disabled)

Read team competition data

Model catalog and project indexes

Read the model catalog

Query reusable project index entries

Upsert reusable project index entries