> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.

# List API OpenAPI Spec

> Read or copy the complete OpenAPI specification behind the List API, to generate a client, import it into your API tooling, or check the exact request and response schemas.

This is the complete specification behind the [List API](/latest/api-rule-list-management), in OpenAPI 3.1 format. Copy it with the button in the top right of the block.

Every endpoint is also documented individually, with an interactive playground you can call your own instance from, starting at [List available lists](/latest/api-reference/list-available-lists).

<Note>
  The `servers` entry uses an `{instance}` variable: replace it with the hostname of your own XCC, without the scheme, for example `xyz.activeguard.cloud`.
</Note>

<div className="wide-code-block">
  ```yaml lists-api-v1.yaml theme={null}
  openapi: 3.1.0
  info:
    title: xorlab Public Lists API
    version: "1.0.0"
    description: >
      Public API for tenant-scoped or deployment-global list operations.
      All endpoints are authenticated with API keys and exposed under
      `/api/public/lists/v1`.
  servers:
    - url: https://{instance}/api
      description: Your own xorlab Control Center.
      variables:
        instance:
          default: xyz.activeguard.cloud
          description: >-
            Hostname of your xorlab Control Center, without the scheme,
            for example xyz.activeguard.cloud.
  security:
    - apiKeyAuth: []
  paths:
    /public/lists/v1/getLists:
      post:
        summary: List available lists
        operationId: publicListsGetLists
        description: >
          Returns metadata for all lists in one tenant-scoped or deployment-global scope.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsGetListsRequest"
        responses:
          "200":
            description: List metadata.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PublicListsGetListsResponse"
          "400":
            description: Invalid request.
          "404":
            description: Unknown tenant scope.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
    /public/lists/v1/listEntries:
      post:
        summary: List all entries from one list
        operationId: publicListsListEntries
        description: >
          Streams all entries from one list scope as NDJSON. Each line is one `PublicListsEntry`.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsListEntriesRequest"
        responses:
          "200":
            description: NDJSON stream of list entries.
            content:
              application/x-ndjson:
                schema:
                  type: string
                  description: Newline-delimited JSON stream of `PublicListsEntry` records.
          "400":
            description: Invalid request.
          "404":
            description: Unknown tenant scope or unknown list.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                    - LIST_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
    /public/lists/v1/addEntries:
      post:
        summary: Add list entries in bulk
        operationId: publicListsAddEntries
        description: >
          Adds entries to one tenant-scoped or deployment-global list.
          Requests can contain at most 500 entries.
          Existing entries are updated and counted as modifications.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsBulkAddEntriesRequest"
        responses:
          "200":
            description: Number of entries effectively added.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PublicListsBulkModificationResponse"
          "400":
            description: Invalid request (for example too many entries).
          "404":
            description: Unknown tenant scope or unknown list.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                    - LIST_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
    /public/lists/v1/deleteEntries:
      post:
        summary: Delete list entries in bulk
        operationId: publicListsDeleteEntries
        description: >
          Deletes entries from one tenant-scoped or deployment-global list.
          Requests can contain at most 500 entries.
          Missing entries are ignored and not counted as modifications.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicListsBulkDeleteEntriesRequest"
        responses:
          "200":
            description: Number of entries effectively deleted.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/PublicListsBulkModificationResponse"
          "400":
            description: Invalid request (for example too many entries).
          "404":
            description: Unknown tenant scope or unknown list.
            headers:
              X-Xor-Response-Status:
                schema:
                  type: string
                  enum:
                    - TENANT_NOT_FOUND
                    - LIST_NOT_FOUND
                description: xorlab-specific status indicating why the resource was not found.
          "403":
            description: Missing required permission.
          "500":
            description: Internal server error.
  components:
    securitySchemes:
      apiKeyAuth:
        type: apiKey
        in: header
        name: Authorization
        x-default: "apikey <your-api-key>"
        description: Use format `apikey <token>`.
    schemas:
      PublicListsGetListsRequest:
        type: object
        additionalProperties: false
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
      PublicListsGetListsResponse:
        type: object
        additionalProperties: false
        required:
          - listFileInfos
        properties:
          listFileInfos:
            type: array
            items:
              $ref: "#/components/schemas/PublicListsFileInfo"
      PublicListsFileInfo:
        type: object
        additionalProperties: false
        required:
          - listInfo
          - listName
        properties:
          listInfo:
            $ref: "#/components/schemas/PublicListsInfo"
          listName:
            type: string
      PublicListsInfo:
        type: object
        additionalProperties: false
        required:
          - displayName
          - category
          - description
          - maxSize
        properties:
          displayName:
            type: string
          category:
            type: string
          description:
            type: string
          maxSize:
            type: integer
            format: int64
      PublicListsListEntriesRequest:
        type: object
        additionalProperties: false
        required:
          - listName
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
          listName:
            type: string
      PublicListsAddEntryRequest:
        type: object
        additionalProperties: false
        required:
          - entry
        properties:
          entry:
            type: string
          comment:
            type:
              - string
              - "null"
      PublicListsBulkAddEntriesRequest:
        type: object
        additionalProperties: false
        required:
          - listName
          - entries
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
          listName:
            type: string
          entries:
            type: array
            maxItems: 500
            items:
              $ref: "#/components/schemas/PublicListsAddEntryRequest"
      PublicListsBulkDeleteEntriesRequest:
        type: object
        additionalProperties: false
        required:
          - listName
          - entries
        properties:
          tenantUid:
            type:
              - string
              - "null"
            format: uuid
            description: If null, the deployment-global list scope is used.
          listName:
            type: string
          entries:
            type: array
            maxItems: 500
            items:
              type: string
      PublicListsBulkModificationResponse:
        type: object
        additionalProperties: false
        required:
          - modifiedEntries
        properties:
          modifiedEntries:
            type: integer
            format: int32
            minimum: 0
      PublicListsEntry:
        type: object
        additionalProperties: false
        required:
          - entry
        properties:
          entry:
            type: string
          comment:
            type:
              - string
              - "null"
          updatedBy:
            type:
              - string
              - "null"
          timeUpdated:
            type:
              - string
              - "null"
            format: date-time
          timeCreated:
            type:
              - string
              - "null"
            format: date-time
  ```
</div>