API Reference

The Infracodebase REST API exposes the same surface the web app uses. Authenticate with a personal access token (icb_pat_…) or an enterprise access token (icb_eat_…) and you can list workspaces, attach rulesets, connect repositories, run compliance evaluations, and start agent runs from outside the UI. See Access Tokens for how to mint one.

Open the portal

The interactive reference is generated from the OpenAPI 3.1 spec and includes per-endpoint request/response shapes, an in-browser request runner, and code samples.

• API portal: /api/v1/docs
• OpenAPI spec: /api/v1/openapi.json

How endpoints are organized

The portal groups endpoints by the entity that owns them, mirroring how the product is structured:

• User: the calling identity. Profile, memberships, and personal rulesets.
• Enterprise: an enterprise and the things attached to it. Enterprise rulesets and the GitHub App integration.
• Workspace: a governed repository tree inside an enterprise. The workspace itself, its attached rulesets (the effective set, including inherited enterprise rulesets), the connected repository, compliance evaluations, and agent runs.

Every URL reflects ownership. Workspace-owned resources sit under /enterprises/{eid}/workspaces/{wid}/...; enterprise-owned resources sit under /enterprises/{eid}/...; user-scoped resources sit under /me/....

Versioning

The v1 surface is semver-style. Additive changes (new fields, new endpoints) ship without a version bump; breaking changes ship at /v2. Endpoints that are documented but pending implementation return 501 not_implemented so the SDK surface is complete ahead of every operation landing.

Authentication

Send the token as a Bearer credential on the Authorization header:

Authorization: Bearer icb_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Both token types are accepted; the server picks the right verification path from the prefix. Tokens carry the permissions of their owner (personal) or the permission set chosen at creation (enterprise).

Compliance exceptions

When a rule fails and the code can't or shouldn't change, a workspace can carry an exception for that rule. There are two kinds:

• Risk acceptance (risk_acceptance): the rule is genuinely violated and someone accepts the risk. The rule counts as passing.
• Not applicable (not_applicable): the rule doesn't apply at this level, for example a control that's set per subscription or per tenant rather than in this code. The rule is removed from scoring.

POST /enterprises/{eid}/workspaces/{wid}/compliance/exceptions opens a request by default, and a compliance approver reviews it. If you hold workspace.compliance.approve or enterprise.compliance.approve, you can pass "mode": "grant" to put the exception in force immediately with no review. A grant from anyone else is refused rather than turned into a request. Exceptions never expire unless you set expires_in_days. Rules marked as required can't carry an exception.

Approvers can approve, reject, or revoke through the same resource, and GET .../compliance/exceptions lists what's active and what's waiting. Findings carry an exception field showing the workspace's current exception on each rule. Only an active exception waives the rule: a stale one was granted against rule text that has since changed, and a pending one is still waiting on review.

Exception decisions are recorded under the name of the person who made them, so they need a personal access token or an MCP sign-in. Enterprise access tokens can list exceptions but can't request, grant, approve, reject, or revoke them.

Draft before a workspace exists

Use the drafting endpoints when you need the same coding guidance, rules, modules, and governance context that a workspace would receive, but you have not created or linked the workspace yet.

GET /api/v1/build-context returns the context needed to plan or generate infrastructure. Select the scope with these parameters.

• Pass workspace_id for an existing workspace.
• Pass repo_url to resolve a repository to a linked workspace when one exists.
• Pass enterprise_id for enterprise-level drafting before a repository is linked.

workspace_id and repo_url cannot be used together. If you pass none of them, the response uses your enterprise when you belong to exactly one, and otherwise returns needs_enterprise with the enterprises you can choose from. You can also pass iac_tool, branch, and a comma-separated ruleset_ids list. The response says whether the repository is linked, whether generation can proceed, and whether the caller must choose an enterprise or rulesets before continuing.

curl "https://infracodebase.com/api/v1/build-context?enterprise_id=ENTERPRISE_ID&iac_tool=terraform" \
  -H "Authorization: Bearer icb_pat_xxx"

After someone chooses optional rulesets, call GET /api/v1/build-rules to load the selected rule content without fetching the full project context again. Pass the enterprise and the selected ruleset IDs. The response includes required rulesets automatically and returns a reusable setup selection.

curl "https://infracodebase.com/api/v1/build-rules?enterprise_id=ENTERPRISE_ID&ruleset_ids=RULESET_ID" \
  -H "Authorization: Bearer icb_pat_xxx"

Both endpoints enforce the token owner's enterprise and workspace permissions. Use the API portal for the complete request and response schemas.

Work sharing and workspace Context

Reasoning effort

Send effort with the initial or any subsequent message to POST /api/v1/enterprises/{eid}/workspaces/{wid}/work/conversations/{tid}/messages.

{
  "content": "Review this workspace for potential issues",
  "client_id": "f8dd3792-d613-4659-92b4-d6716abac6bb",
  "effort": "high"
}

Accepted values are low, medium, high, xhigh, and max. Omission uses medium for that message. API requests do not read or change browser preferences. The setting applies to the queued run and stays the same on retries. A duplicate client_id with different effort returns 409 and preserves the original request.

Run responses include requested_effort, effective_effort, and model. The effective value is recorded when the worker configures the SDK. Models without effort support ignore the setting and report effective_effort: null. Unsupported levels on an effort-capable model fall back to medium. Before configuration, the effective value and model are null. Historical runs can also have null effort. These fields record configuration, not a measurement of reasoning performed.

The older /runs endpoints remain unimplemented. Use the Work conversation routes to execute requests.

Conversation access

Work conversations remain private until their owner grants access. Under /api/v1/enterprises/{eid}/workspaces/{wid}/work/conversations/{tid}, GET /sharing returns the current version, explicit grants, and eligible workspace members. Use ?search= to narrow candidates by name or email. Candidate discovery examines up to 50 matching enterprise members and returns those with workspace access. Only conversation owners can read or change sharing. The response also includes teams assigned to the workspace and identifies team grants with a team object.

POST /sharing accepts exactly one of user_id or team_id, a role (VIEWER, CONTRIBUTOR, or null to revoke), and expected_version. A stale version returns 409. Sharing does not grant workspace access. Contributors also need workspace editing permission to send work. A copied conversation link does not bypass these access checks. Team access follows current manual membership and active linked directory groups. Removing membership, disconnecting the directory, or revoking the team grant removes inherited access. When several grants apply, the highest conversation role wins. Personal bookmarks do not grant access and are not shared with teammates.

Files and reference links live in shared workspace Context, independently of a conversation. Under /api/v1/enterprises/{eid}/workspaces/{wid}/context, use these routes.

FileInfo contains id, filename, mime_type, size_bytes, created_at, description (null when empty), and tags. LinkInfo contains id, url, title, created_at, description (empty string when unset), reason, and tags. The legacy reason field remains an alias for a link's description. Creation accepts reason instead of description; if both are supplied, they must match. Updates use description.

Descriptions accept up to 500 characters. Each item accepts up to 10 tags, supplied as { "name": "architecture", "color": "blue" }. Names are normalized to lowercase with dashes and must contain 1–50 characters. Duplicate normalized names are rejected. Colors are blue (default), cyan, teal, mint, green, lime, indigo, brown, purple, pink, red, orange, tangerine, and yellow. Tags are shared within a workspace. Reusing an existing name preserves its color. Responses include each tag's id, normalized name, color, and Spectrum color_hex.

On PATCH, omitted fields stay unchanged. An empty description clears it. Supplying tags replaces the item's tags; [] clears all tags. Updates do not change file bytes, filenames, link URLs, or link titles.

Supported uploads

All supported types accept the same description and tags fields.

Uploads accept one file up to 100 MB. Agent document processing has a separate 10 MB limit, and accepting an upload does not guarantee text extraction for every format. PowerPoint, SVG, HEIC, Visio, and draw.io files are not supported by this upload API. Repeated file contents return the existing document without replacing its metadata. Repeated normalized URLs likewise preserve the existing link and its metadata. Use PATCH to update them explicitly.

Links must use public HTTPS addresses without embedded credentials or access tokens. Saving a link does not fetch the page. Deleting a link only removes the reference. Deleting a document permanently removes its stored file and metadata. Existing Work messages remain, but references to a deleted file can no longer be read. A missing item returns 404. Storage deletion failures return an error and retain the file's metadata so deletion can be retried.

Upload and update examples

BASE_URL is your deployment origin, for example https://infracodebase.com. Use a personal or enterprise access token in TOKEN and the enterprise and workspace IDs in the path.

CONTEXT="$BASE_URL/api/v1/enterprises/$ENTERPRISE_ID/workspaces/$WORKSPACE_ID/context"
curl "$CONTEXT/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'file=@architecture.pdf' \
  -F 'description=Architecture decisions and deployment requirements.' \
  -F 'tags=[{"name":"architecture","color":"blue"}]'

curl "$CONTEXT/links" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.aws.amazon.com/lambda/latest/dg/urls-auth.html","title":"Lambda URL authentication","description":"Official authentication reference.","tags":[{"name":"aws","color":"orange"}]}'

curl -X PATCH "$CONTEXT/files/$FILE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"description":"Reviewed architecture decisions.","tags":[{"name":"reviewed","color":"green"}]}'

curl -X DELETE "$CONTEXT/links/$LINK_ID" \
  -H "Authorization: Bearer $TOKEN"

Use Context in Work

To include an uploaded file in a Work request, pass its ID in file_ids when posting a message. Files must belong to the same workspace. Up to 20 documents can be attached.

{
  "content": "Review the attached architecture and suggest improvements.",
  "client_id": "2e0c4e94-46b0-48ab-a66b-c348fc93a384",
  "file_ids": ["8c3acee9-8121-42d4-b067-1b5e710d3cfa"]
}

Listing or attaching documents requires workspace.docs.view. Adding, updating, or deleting files or links requires workspace.docs.manage, workspace editing permission, and an execute scope. Enterprise tokens must also include the workspace in their scope. Context added by API is visible in the Context tab to people with document access. It is not private to the conversation that uses it.

Create a conversation first, then send a message using the returned conversation id. Generate a fresh UUID for each logical client_id, and reuse it when retrying that same request to avoid creating duplicate conversations or runs.

WORK="$BASE_URL/api/v1/enterprises/$ENTERPRISE_ID/workspaces/$WORKSPACE_ID/work/conversations"
curl "$WORK" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Review architecture","client_id":"d908f125-082d-4433-9c24-0c873996fb34"}'

# Set CONVERSATION_ID to the returned id and FILE_ID to the uploaded file's data.id.
curl "$WORK/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"content\":\"Review the attached architecture.\",\"client_id\":\"6cf49910-8001-48af-926d-ff2654b73990\",\"file_ids\":[\"$FILE_ID\"]}"

curl "$WORK/$CONVERSATION_ID/runs" -H "Authorization: Bearer $TOKEN"
curl "$WORK/$CONVERSATION_ID/messages" -H "Authorization: Bearer $TOKEN"

Message submission returns 202 with { message_id, run }, not the final answer. Read /runs for execution state and /messages for the conversation output. Reference links are shared workspace Context, not file_ids; include the relevant URL in your message when you want the agent to use it. Agent Work must be enabled for the enterprise, and the caller needs the required workspace and conversation permissions in addition to document access.