> ## Documentation Index > Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt > Use this file to discover all available pages before exploring further. # Publish the working set > Publishes the working set as a new version. Deployment is asynchronous: poll `GET /{listId}/status` until `live`. Requires an admin API key, the **Admin (tenant-wide)** key type, which only an owner or admin of this organization can create. **Workspace scoped** and **Tenant scoped** keys are refused with 403. The `x-user-token` scheme is the Minerva dashboard session token; with it, writes require an owner or admin. ## OpenAPI ````yaml /api-reference/admin-api.json post /custom-lists/v2/organizations/{orgId}/{listId}/publish openapi: 3.0.0 info: version: 1.0.0 title: MinervaAI Admin API description: Admin endpoints for the Minerva application suite. servers: - url: https://api.gominerva.com description: The production API server for Minerva. security: - ApiKeyAuth: [] tags: [] paths: /custom-lists/v2/organizations/{orgId}/{listId}/publish: post: tags: - Custom Lists summary: Publish the working set description: >- Publishes the working set as a new version. Deployment is asynchronous: poll `GET /{listId}/status` until `live`. Requires an admin API key, the **Admin (tenant-wide)** key type, which only an owner or admin of this organization can create. **Workspace scoped** and **Tenant scoped** keys are refused with 403. The `x-user-token` scheme is the Minerva dashboard session token; with it, writes require an owner or admin. parameters: - in: path name: orgId required: true schema: type: string description: >- The organization (tenant) id. Must equal the tenant of the admin key. - in: path name: listId required: true schema: type: string description: The custom list id. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomListRevisionRequest' examples: publish: summary: Publish the working set at the revision you last read. value: expected_revision: 1 responses: '202': description: Accepted; the version is deploying. content: application/json: schema: $ref: '#/components/schemas/CustomListVersionResponse' examples: accepted: summary: The new version was created and deployment is queued. value: data: id: 4a3b2c1d-8e9f-4a6b-9c7d-6e5f4a3b2c1d tenant_id: 123e4567-e89b-12d3-a456-426614174000 list_id: 3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c version_number: 1 status: published record_count: 1 active_record_count: 1 content_checksum: >- f22defdbee04a9a66378aea4a7d99aa4c9c0c031856abfbd3f946290a5ae845e index_artifact_ref: >- versions/123e4567-e89b-12d3-a456-426614174000/3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c/f22defdbee04a9a66378aea4a7d99aa4c9c0c031856abfbd3f946290a5ae845e.jsonl published_by: 64b1c0de00000000000000a1 published_at: '2026-11-05T01:18:56.664Z' name: Offboarded clients description: Clients we no longer do business with risk_score_impact: 0 '400': description: >- Invalid request: a required field is missing or a value is invalid. Some validation errors (for example `name is required.`) are plain text; others (`error` is `validation_failed`) are a JSON `CustomListError`. Branch on `Content-Type`. content: text/plain: schema: type: string example: expected_revision must be a non-negative integer. application/json: schema: $ref: '#/components/schemas/CustomListError' '403': description: >- No credentials were sent; the API key was revoked, has expired, or its application is deactivated (`API-key authentication was denied.`); the key is not an admin application key (**Workspace scoped** and **Tenant scoped** keys are refused); it belongs to another organization; or its creator is no longer an owner or admin. For a user token, the user is not a member, or is not an owner or admin on a write. If the tenant is not entitled to custom lists, the body is a JSON `CustomListError` with `error: not_enabled` (`Custom lists are not enabled for this tenant.`); every other 403 is plain text. Branch on `Content-Type`. content: text/plain: schema: type: string example: 'Missing Authorization: Api-Key or x-api-key header.' application/json: schema: $ref: '#/components/schemas/CustomListError' examples: not-enabled: summary: Tenant not entitled. value: error: not_enabled message: Custom lists are not enabled for this tenant. '404': description: >- Custom list management is not enabled (`Custom list management is not enabled.`); the list, record, upload, job or workspace is not in this organization; or the application API key (`mrva-…`) is unknown (`API-key authentication was denied.`). content: text/plain: schema: type: string example: Custom list management is not enabled. '409': description: >- The list's working set changed since `expected_revision` was read (or another write conflicts). Re-read `working_set_revision` from `GET /{listId}/pending-changes`, review the changes, and retry with it. JSON `CustomListError` with `error: conflict`. content: application/json: schema: $ref: '#/components/schemas/CustomListError' examples: stale-revision: summary: '`expected_revision` is out of date.' value: error: conflict message: >- The working set changed since revision 1; re-read pending changes and retry. retryable: true '422': description: >- A tenant custom-list entitlement limit was exceeded. JSON `CustomListError` with `error: limit_exceeded`, `limit` naming the limit and `max` the configured maximum. `maxActiveCustomListRecordsPerWorkspace` (the new version would push an activated workspace over its cap) is checked before anything is written, so nothing was published. `maxRecordsPerSharedShard` can be returned after the new version was already published, while Minerva redistributes records. Before retrying, re-read `GET /{listId}/status` to see whether the version was published. content: application/json: schema: $ref: '#/components/schemas/CustomListError' examples: version-limit: summary: The tenant retains its maximum number of versions. value: error: limit_exceeded limit: maxPublishedVersionsRetained max: 50 '503': description: >- The authentication service is temporarily unavailable (`Authentication service is unavailable.`). Nothing was changed; retry with backoff. content: text/plain: schema: type: string example: Authentication service is unavailable. security: - AdminApiKeyAuth: [] - UserTokenAuth: [] components: schemas: CustomListRevisionRequest: type: object required: - expected_revision properties: expected_revision: type: integer minimum: 0 description: >- `working_set_revision` from `GET /{listId}/pending-changes`. A stale value is 409. CustomListVersionResponse: type: object description: '`{ data: CustomListVersion }`' properties: data: $ref: '#/components/schemas/CustomListVersion' required: - data CustomListError: type: object properties: error: type: string description: >- Machine-readable code, e.g. `validation_failed`, `limit_exceeded`, `conflict`, `not_enabled`, `upload_capacity_exceeded`, `upload_request_timeout`. message: type: string limit: type: string description: >- For `limit_exceeded`: the entitlement limit, e.g. `maxRecordsPerList`. max: type: integer description: 'For `limit_exceeded`: the configured maximum.' retryable: type: boolean additionalProperties: true CustomListVersion: type: object properties: id: type: string tenant_id: type: string list_id: type: string version_number: type: integer status: type: string enum: - draft - published - failed - retired record_count: type: integer active_record_count: type: integer source_upload_id: type: string content_checksum: type: string index_artifact_ref: type: string deployment_status: type: string enum: - pending - live - down deployment_stage: type: string deployment_health: type: string deployment_job_id: type: string deployment_correlation_id: type: string deployment_failure_reason: type: string published_by: type: string description: >- The actor that published: a user id, or the admin application id for a key request. published_at: type: string format: date-time name: type: string description: type: string risk_score_impact: type: integer required: - id - tenant_id - list_id - version_number - status - record_count - active_record_count - content_checksum securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Admin API key for authentication. Manage API keys in the Minerva dashboard under Administration > Developers. AdminApiKeyAuth: type: apiKey in: header name: Authorization description: >- An admin application key: `Authorization: Api-Key ` (or legacy `x-api-key`). Only tenant owners and admins can create one. Standard keys are refused with 403 on workspace management and tenant configuration routes. UserTokenAuth: type: apiKey in: header name: x-user-token description: Firebase user token for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.