Guides

Advanced guides for structured output, retrieval, agent capabilities, hosted runs, and repo workflows.

Guides

JSON Output

Use response_format with JSON schema when the selected model supports structured output.

JSON schema request

{
  "model": "ipop/coder-balanced",
  "messages": [{ "role": "user", "content": "Return a JSON status object." }],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "status_response",
      "schema": {
        "type": "object",
        "properties": { "status": { "type": "string" } },
        "required": ["status"]
      }
    }
  }
}

Embeddings

Create vectors with the OpenAI-compatible /embeddings shape.

Embedding request

curl https://api.terminaili.com/v1/embeddings \
  -H "Authorization: Bearer $TERMINAILI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "terminaili/embed-balanced",
    "input": "Embed this sentence for retrieval."
  }'

Agent Capabilities

Agent clients can discover generated config, resumable turns, streaming rules, and tool-batch planning.

Agent capabilities OpenCode config Hermes config

GEThttps://api.terminaili.com/v1/agent-capabilities

POSThttps://api.terminaili.com/v1/agent-turns

POSThttps://api.terminaili.com/v1/agent-tool-batches/plan

Capabilities

curl -s "https://api.terminaili.com/v1/agent-capabilities" \
  -H "Authorization: Bearer $TERMINAILI_API_KEY"

Resume turn events

curl -N "https://api.terminaili.com/v1/agent-turns/$REQUEST_ID/events" \
  -H "Authorization: Bearer $TERMINAILI_API_KEY" \
  -H "Last-Event-ID: 0"

Hosted Orchestrations

Hosted orchestration runs coordinate multiple coding roles against a cloud workspace.

ConcurrencyRuns advertise a maximum of 8 parallel tasks and use normalized path locks.

RecoveryUse idempotency keys on create, then poll events, tasks, locks, candidates, and artifacts.

Feature gateHosted execution is enabled when IPOP_ORCHESTRATION_V2_ENABLED is active.

Endpoint	Method	Use
`/v1/orchestrations`	GET	List hosted orchestration runs for the account.
`/v1/orchestrations`	POST	Create a hosted multi-agent orchestration run.
`/v1/orchestrations/{id}`	GET	Read one run and its current summary.
`/v1/orchestrations/{id}/events`	GET	Replay durable orchestration events.
`/v1/orchestrations/{id}/tasks`	GET	List planner, implementer, reviewer, fixer, security, and docs tasks.
`/v1/orchestrations/{id}/locks`	GET	List normalized path locks.
`/v1/orchestrations/{id}/artifacts`	GET	List checkpoints, rollback artifacts, and review outputs.
`/v1/orchestrations/{id}/candidates`	GET	List merge candidates and verification results.
`/v1/orchestrations/{id}/cancel`	POST	Cancel a queued or running orchestration.
`/v1/orchestrations/{id}/merge`	POST	Request merge arbitration.
`/v1/orchestrations/{id}/undo`	POST	Request rollback from a merge decision.
`/v1/orchestrations/{id}/tasks/{task_id}/retry`	POST	Retry an eligible failed or review-needed role task.

Create orchestration

curl "https://api.terminaili.com/v1/orchestrations" \
  -H "Authorization: Bearer $TERMINAILI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: orch_docs_example_001" \
  -d '{
    "workspace": "<workspace_uuid>",
    "prompt": "Implement the issue, run tests, and prepare a review summary.",
    "model": "ipop/coder-balanced",
    "max_parallel": 4,
    "auto_merge": false
  }'

Git Dashboard

The Git dashboard is a repo workbench at /dashboard?section=git.

Open Git dashboard Files Clone

Restore orderURL params win first, then ipop.git.lastWorkbench.v1, then the first hosted repo, then the first GitHub repo, then setup mode.

Focused workbenchA selected repo shows one task at a time: Files, Branches, Clone, CI, or Settings.

Route state

Query param	Allowed values	Use
`git_source`	hosted \| github	Choose managed hosted repos or connected GitHub repos.
`git_repo`	hosted repo id \| owner/name	Select the repo. Invalid values fall back to the saved or first available repo.
`git_task`	files \| branches \| clone \| ci \| settings	Open exactly one workbench task.
`git_ref`	branch or ref	Carry the current branch/ref into Files and CI when it exists.

Tasks

Task	Purpose	URL state
`Files`	Browse a ref, open the file tree, preview a selected file, and review recent commits.	git_task=files
`Branches`	Create branches, list existing branches, and compare or merge only after base and head differ.	git_task=branches
`Clone`	Mint Read only or Read and write clone tokens, then copy the clone or push command output.	git_task=clone
`CI`	Review the latest run, start a workflow, and manage secrets from the advanced area.	git_task=ci
`Settings`	Rename a hosted repo, change the default branch, control CI requirements, or delete the repo.	git_task=settings

Deep link examples

/dashboard?section=git&git_source=hosted&git_repo=repo_123&git_task=files&git_ref=main
/dashboard?section=git&git_source=github&git_repo=acme/app&git_task=ci&git_ref=main
/dashboard?section=git&git_task=clone

FAQ

Is this OpenAI-compatible?

Yes. Set the base URL to /v1, keep the OpenAI Chat Completions or Embeddings shape, and authenticate with your Terminaili key.

Which auth header should I use?

Use Authorization: Bearer $TERMINAILI_API_KEY. The public OpenAPI contract also advertises x-api-key for clients that prefer API-key headers.

How do I pick a model?

Start with ipop/coder-balanced, then use the model picker or /v1/model-recommendations when requirements change.

Can I safely retry failed requests?

Use idempotency-key on chat completions, embeddings, inference, and agent turns. Retry responses include x-request-id, x-retry-safe, and retry-after when applicable.

Change Log

Date	Change	Impact
May 15, 2026	Docs cleanup / public API baseline	API-first docs IA, endpoint reference, FAQ, and changelog.