The
servers entry uses an {instance} variable: replace it with the hostname of your own XCC, without the scheme, for example xyz.activeguard.cloud.lists-api-v1.yaml
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