# API reference

Base URL, authentication, the response envelope, pagination, filters and every public operation of the AutoCISO REST API.

The AutoCISO REST API is a JSON API over HTTPS. Every operation has its own page with parameters, response fields, errors and copy-paste examples. The OpenAPI document is published as [YAML](/openapi/public-v1.yaml) and [JSON](/openapi/public-v1.json).

## Base URL

```text
https://api.autociso.io/api/v1
```

All paths in this reference are relative to the base URL. The published OpenAPI file now declares `servers` as `https://api.autociso.io/api/v1` and carries the `/jml/...` and `/sscs/...` prefixes in its path keys, where it used to put `/jml` into the server URL. The full URLs are unchanged, so existing integrations and generated clients keep working.

## Authentication

Send an API token in the `Authorization` header. Create tokens, and pick their scopes, as described in [API Tokens](/developers/api-tokens/). What each scope and plan allows is in [Access Model & Scopes](/developers/access-model/).

| Header | Value | Required |
|---|---|---|
| `Authorization` | `Bearer <your-api-token>` | Always |
| `Content-Type` | `application/json` | On requests with a body |

## Response envelope

Responses use the envelope `{ data, error, meta }`. On success `data` holds the payload, `error` is `null` and `meta` carries pagination or summary values. On failure `data` is `null` and `error` is `{ code, message }`. The Supply Chain (SSCS) operations return a success body with `data` only and omit `error` and `meta`; the reference page of each operation shows its exact shape. Failures of every operation use the error codes in [Errors & Rate Limits](/developers/errors-and-limits/).

## Pagination

List operations that paginate report it in `meta`. Which shape applies is stated on the operation page.

| Style | Request parameters | `meta` |
|---|---|---|
| Offset | `limit`, `offset` | `{ total, limit, offset }` |
| Cursor | `limit`, `cursor` | `{ limit, hasMore, nextCursor }` |

Cursor pagination is coming with the registry routes: no operation in this reference uses it yet. SSCS list operations return the whole list and do not paginate.

## Filtering and sorting

Operations that support filters take them as `filter[field][op]=value`, for example `filter[status][in]=OUTSTANDING,DISCREPANCY`. The operators are `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `re` and `exists`. Sorting is `sort[field]=asc` or `sort[field]=desc`, and `q=term` searches. Each operation page lists the fields it accepts; an unknown field is rejected with `VALIDATION_FAILED`.

## Response headers

| Header | Status |
|---|---|
| `Retry-After` | Sent on `429 RATE_LIMITED`, in whole seconds (at least 1). Wait that long before retrying. |
| `X-Request-ID` | Not yet sent by the API. |
| `RateLimit-*` | Not yet sent by the API. Limits are described in [Errors & Rate Limits](/developers/errors-and-limits/). |

## Operations

71 operations. Scope is the token scope the operation requires; Plan is the lowest plan that includes it.

| Resource | Method | Path | Operation | Scope | Plan |
|---|---|---|---|---|---|
| Off-boarding | GET | `/jml/offboarding/cases` | [List leaver cases](/api/reference/offboarding-cases/list/) | `jml:read` | Seed+ |
| Off-boarding | GET | `/jml/offboarding/cases/{caseId}` | [Get a leaver case](/api/reference/offboarding-cases/get/) | `jml:read` | Seed+ |
| Off-boarding | GET | `/jml/offboarding/cases/{caseId}/items` | [List the items of a leaver case](/api/reference/offboarding-case-items/list/) | `jml:read` | Seed+ |
| Off-boarding | GET | `/jml/offboarding/items` | [List leaver items across cases (feed)](/api/reference/offboarding-items/list/) | `jml:read` | Seed+ |
| On-boarding | GET | `/jml/onboarding/cases` | [List joiner cases](/api/reference/onboarding-cases/list/) | `jml:read` | Seed+ |
| On-boarding | GET | `/jml/onboarding/cases/{caseId}` | [Get a joiner case](/api/reference/onboarding-cases/get/) | `jml:read` | Seed+ |
| On-boarding | GET | `/jml/onboarding/cases/{caseId}/items` | [List the items of a joiner case](/api/reference/onboarding-case-items/list/) | `jml:read` | Seed+ |
| On-boarding | GET | `/jml/onboarding/items` | [List joiner items across cases (feed)](/api/reference/onboarding-items/list/) | `jml:read` | Seed+ |
| SBOMs | GET | `/sscs/sboms` | [List SBOMs](/api/reference/sboms/list/) | `sbom:read` | Growth+ |
| SBOMs | POST | `/sscs/sboms` | [Create SBOM](/api/reference/sboms/create/) | `sbom:write` | Growth+ |
| SBOMs | POST | `/sscs/sboms/upload` | [Upload SBOM manifest](/api/reference/sboms/upload/) | `sbom:write` | Growth+ |
| SBOMs | GET | `/sscs/sboms/{sbomId}` | [Get SBOM](/api/reference/sboms/get/) | `sbom:read` | Growth+ |
| SBOMs | DELETE | `/sscs/sboms/{sbomId}` | [Delete SBOM](/api/reference/sboms/delete/) | `sbom:write` | Growth+ |
| SBOMs | GET | `/sscs/sboms/{sbomId}/components` | [List SBOM components](/api/reference/sboms/list-components/) | `sbom:read` | Growth+ |
| Findings | GET | `/sscs/findings` | [List findings](/api/reference/findings/list/) | `sbom:read` | Growth+ |
| Findings | GET | `/sscs/findings/summary` | [Findings summary](/api/reference/findings/summary/) | `sbom:read` | Growth+ |
| Findings | PATCH | `/sscs/findings/{findingId}/status` | [Update finding status](/api/reference/findings/update-status/) | `sbom:write` | Growth+ |
| Vendors | GET | `/sscs/vendors` | [List vendors](/api/reference/vendors/list/) | `sbom:read` | Growth+ |
| Vendors | POST | `/sscs/vendors` | [Create vendor](/api/reference/vendors/create/) | `sbom:write` | Growth+ |
| Vendors | GET | `/sscs/vendors/risk-summary` | [Vendor risk summary](/api/reference/vendors/risk-summary/) | `sbom:read` | Growth+ |
| Vendors | PUT | `/sscs/vendors/{vendorId}` | [Update vendor](/api/reference/vendors/update/) | `sbom:write` | Growth+ |
| Supplier questionnaires | GET | `/supplier-assessment-templates` | [List supplier questionnaires](/api/reference/supplier-templates/list/) | `supplier_template:read` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates` | [Create a questionnaire](/api/reference/supplier-templates/create/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/clone` | [Clone a questionnaire](/api/reference/supplier-templates/clone/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | GET | `/supplier-assessment-templates/{templateId}` | [Get a questionnaire](/api/reference/supplier-templates/get/) | `supplier_template:read` | Growth+ |
| Supplier questionnaires | GET | `/supplier-assessment-templates/{templateId}/versions/{version}` | [Get a questionnaire version](/api/reference/supplier-templates/get-version/) | `supplier_template:read` | Growth+ |
| Supplier questionnaires | GET | `/supplier-assessment-templates/{templateId}/versions/{version}/diff/{otherVersion}` | [Compare two questionnaire versions](/api/reference/supplier-templates/diff-versions/) | `supplier_template:read` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/validate` | [Validate a draft](/api/reference/supplier-templates/validate/) | `supplier_template:read` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/publish/preview` | [Preview publishing a draft](/api/reference/supplier-templates/preview-publish/) | `supplier_template:read` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/draft` | [Open a draft of a published questionnaire](/api/reference/supplier-templates/open-draft/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | PATCH | `/supplier-assessment-templates/{templateId}/meta` | [Edit the title, description and modes of a draft](/api/reference/supplier-templates/update-meta/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/sections` | [Add a section to a draft](/api/reference/supplier-templates/add-section/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | PATCH | `/supplier-assessment-templates/{templateId}/sections/{sectionId}` | [Rename a section of a draft](/api/reference/supplier-templates/rename-section/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | DELETE | `/supplier-assessment-templates/{templateId}/sections/{sectionId}` | [Delete a section of a draft](/api/reference/supplier-templates/delete-section/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/translate` | [Translate one questionnaire field](/api/reference/supplier-templates/translate/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/questions` | [Add a question to a section of a draft](/api/reference/supplier-templates/add-question/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | PATCH | `/supplier-assessment-templates/{templateId}/questions/{questionId}` | [Edit a question of a draft](/api/reference/supplier-templates/update-question/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | DELETE | `/supplier-assessment-templates/{templateId}/questions/{questionId}` | [Delete a question of a draft](/api/reference/supplier-templates/delete-question/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/questions/{questionId}/options` | [Add an option to a choice question of a draft](/api/reference/supplier-templates/add-option/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | PATCH | `/supplier-assessment-templates/{templateId}/questions/{questionId}/options/{optionId}` | [Edit an option of a draft question](/api/reference/supplier-templates/update-option/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | DELETE | `/supplier-assessment-templates/{templateId}/questions/{questionId}/options/{optionId}` | [Delete an option of a draft question](/api/reference/supplier-templates/delete-option/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/submit` | [Submit a draft for approval](/api/reference/supplier-templates/submit/) | `supplier_template:write` | Growth+ |
| Supplier questionnaires | POST | `/supplier-assessment-templates/{templateId}/withdraw` | [Withdraw a submitted draft](/api/reference/supplier-templates/withdraw/) | `supplier_template:write` | Growth+ |
| API Tokens | GET | `/tokens` | [List API tokens](/api/reference/tokens/list/) | Console session (Owner or Manager) | Included |
| API Tokens | POST | `/tokens` | [Create an API token](/api/reference/tokens/create/) | Console session (Owner or Manager) | Included |
| API Tokens | GET | `/tokens/scopes` | [List assignable token scopes](/api/reference/token-scopes/list/) | Console session (Owner or Manager) | Included |
| API Tokens | DELETE | `/tokens/{tokenId}` | [Revoke an API token](/api/reference/tokens/revoke/) | Console session (Owner or Manager) | Included |
| Health | GET | `/health` | [Check API health](/api/reference/health/check/) | None (public) | Included |
| Access | GET | `/access` | [List the access inventory (one row per grant)](/api/reference/access/list/) | `access_review:read` | Included |
| Assets | GET | `/assets` | [List assets](/api/reference/assets/list/) | `asset:read` | Included |
| Audit trail | GET | `/audit-trail` | [List audit trail entries (ids, codes and chain fields only)](/api/reference/audit-trail/list/) | `audit_log:read` | Growth+ |
| Audit trail | GET | `/audit-trail/verify` | [Verify the audit trail hash chain](/api/reference/audit-trail/verify/) | `audit_log:verify` | Growth+ |
| Compliance | GET | `/compliance/overview` | [Get the compliance posture overview (scores, counts, trend)](/api/reference/compliance/get-overview/) | `compliance:read` | Growth+ |
| Compliance | GET | `/compliance/states` | [List control reliability states](/api/reference/compliance/list-states/) | `compliance:read` | Scale+ |
| Employees | GET | `/employees` | [List employees (identity with pii:read only)](/api/reference/employees/list/) | `employee:read` | Included |
| Employees | GET | `/employees/{id}/access-history` | [List an employee's access events](/api/reference/employees/get-access-history/) | `employee:read` | Included |
| ISO projects | GET | `/iso/projects` | [List ISO projects](/api/reference/iso-projects/list/) | `iso:read` | Growth+ |
| ISO projects | GET | `/iso/projects/{projectId}` | [Get one ISO project](/api/reference/iso-projects/get/) | `iso:read` | Growth+ |
| ISO projects | GET | `/iso/projects/{projectId}/evidence` | [List a project's evidence metadata](/api/reference/iso-projects/list-evidence/) | `evidence:read` | Growth+ |
| ISO projects | GET | `/iso/projects/{projectId}/gap` | [List a project's gap controls](/api/reference/iso-projects/list-gap/) | `iso:read` | Growth+ |
| Monitoring | GET | `/iso/projects/{projectId}/monitoring` | [Get a project's continuous monitoring status](/api/reference/iso-projects/get-monitoring/) | `compliance:read` | Scale+ |
| ISO projects | GET | `/iso/projects/{projectId}/policies` | [List a project's policies with acknowledgement counts](/api/reference/iso-projects/list-policies/) | `iso:read` | Growth+ |
| ISO projects | GET | `/iso/projects/{projectId}/readiness` | [Get a project's audit readiness (codes and counts)](/api/reference/iso-projects/get-readiness/) | `iso:read` | Growth+ |
| ISO projects | GET | `/iso/projects/{projectId}/roadmap` | [List a project's roadmap tasks](/api/reference/iso-projects/list-roadmap/) | `iso:read` | Growth+ |
| ISO projects | GET | `/iso/projects/{projectId}/soa` | [List a project's Statement of Applicability entries](/api/reference/iso-projects/list-soa/) | `iso:read` | Growth+ |
| Risk records | GET | `/risk/records` | [List risk records](/api/reference/risk-records/list/) | `risk:read` | Growth+ |
| Risk records | GET | `/risk/records/{id}` | [Get one risk record](/api/reference/risk-records/get/) | `risk:read` | Growth+ |
| Suppliers | GET | `/suppliers` | [List suppliers](/api/reference/suppliers/list/) | `supplier:read` | Included |
| Suppliers | GET | `/suppliers/{supplierId}` | [Get one supplier](/api/reference/suppliers/get/) | `supplier:read` | Included |
| Suppliers | GET | `/suppliers/{supplierId}/agreements` | [List a supplier's agreements](/api/reference/suppliers/list-agreements/) | `supplier:read` | Included |
| Suppliers | GET | `/suppliers/{supplierId}/assessments` | [List a supplier's assessments](/api/reference/suppliers/list-assessments/) | `supplier:read` | Included |