> ## Documentation Index > Fetch the complete documentation index at: https://cntillion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a Helpdesk ticket > Open a Helpdesk ticket for a Centillion agent from your own systems Authenticate with a Full access workspace API key, or as an active Owner, Member, or Support Associate in the workspace that owns the agent. A read-only key or a Viewer receives `403 FORBIDDEN`. See [authentication](https://cntillion.com/docs/api-reference/introduction.md#authentication) and [workspace roles](https://cntillion.com/docs/workspaces/members.md). ## OpenAPI ````yaml POST /api/v2/agents/{agentId}/helpdesk/tickets openapi: 3.0.1 info: title: Centillion Labs API description: Public API endpoints for Centillion Labs agents, testing, and Helpdesk. version: 2.0.0 servers: [] security: - bearerAuth: [] - workspaceApiKey: [] tags: - name: Agent testing description: Workspace tests, agent suites, execution, and results. paths: /api/v2/agents/{agentId}/helpdesk/tickets: post: summary: Create a Helpdesk ticket description: >- Creates a customer-authored Helpdesk ticket with API origin. When no assignee is supplied, the agent's assignment rules and triggers run. Reusing an Idempotency-Key with the same body returns the original ticket without consuming another ticket number. operationId: createHelpdeskTicket parameters: - name: agentId in: path required: true description: Agent ID in the authenticated workspace. schema: type: string minLength: 1 maxLength: 128 - name: Idempotency-Key in: header required: true description: >- A caller-generated key, unique to this logical ticket creation. Replays must send the same request body. schema: type: string minLength: 1 maxLength: 128 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateHelpdeskTicket' responses: '201': description: The new or idempotently replayed ticket. headers: Idempotent-Replayed: description: >- True when this response returned a ticket created by an earlier request. schema: type: boolean x-request-id: description: Request identifier for support and diagnostics. schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/HelpdeskTicket' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- FORBIDDEN: the caller is not an active workspace Owner, Member, or Support Associate, or the workspace key is read-only. PLAN_REQUIRED: the workspace plan does not include Helpdesk. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': description: >- RATE_LIMIT_TOO_MANY_REQUESTS: the workspace key sent more than 100 requests in 10 seconds. Retry after the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': $ref: '#/components/responses/InternalError' components: schemas: CreateHelpdeskTicket: type: object additionalProperties: false required: - subject - description - customer properties: subject: type: string minLength: 1 maxLength: 500 description: type: string minLength: 1 maxLength: 10000 customer: type: object additionalProperties: false required: - email properties: email: type: string format: email maxLength: 320 name: type: string minLength: 1 maxLength: 255 statusId: type: string description: >- An active status belonging to this agent. Do not combine with statusCategory. statusCategory: type: string description: >- Uses the agent's default status for this category. Defaults to new. Do not combine with statusId. enum: - new - on_you - on_customer - on_hold - closed - cancelled assigneeId: type: string nullable: true description: >- An active Helpdesk member ID, or null to suppress automatic assignment. Do not combine with assigneeEmail. assigneeEmail: type: string format: email description: An active Helpdesk member email. Do not combine with assigneeId. teamId: type: string description: >- A team belonging to this agent. The default team is used when omitted. customFields: type: object description: >- Up to 50 active custom fields keyed by field ID. Dropdown values use option IDs. Dates use YYYY-MM-DD. maxProperties: 50 additionalProperties: nullable: true oneOf: - type: string maxLength: 2000 - type: boolean HelpdeskTicket: type: object required: - ticketNumber - subject - description - statusCategory - statusId - assigneeId - customer - customFields - channel - teamId - createdAt - updatedAt - lastMessageAt properties: ticketNumber: type: integer subject: type: string description: type: string statusCategory: type: string enum: - new - on_you - on_customer - on_hold - closed - cancelled statusId: type: string assigneeId: type: string nullable: true customer: type: object required: - id - name - email properties: id: type: string name: type: string nullable: true email: type: string format: email nullable: true customFields: type: object additionalProperties: nullable: true oneOf: - type: string - type: boolean channel: type: string enum: - api teamId: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time lastMessageAt: type: string format: date-time nullable: true ApiError: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: {} responses: BadRequest: description: The request or idempotency header is invalid. content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: The bearer token or authenticated session is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: >- The agent does not exist in the authenticated workspace or Helpdesk is disabled. content: application/json: schema: $ref: '#/components/schemas/ApiError' Conflict: description: >- The idempotency key was used for another request, or Helpdesk lacks a required default. content: application/json: schema: $ref: '#/components/schemas/ApiError' RequestTooLarge: description: The request body exceeds 64 KB. content: application/json: schema: $ref: '#/components/schemas/ApiError' UnprocessableEntity: description: >- A status, team, assignee, or custom field is outside this agent or cannot accept the supplied value. content: application/json: schema: $ref: '#/components/schemas/ApiError' InternalError: description: The ticket could not be created. content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Clerk session token description: >- A Clerk bearer token associated with the active workspace. Browser sessions may use their authenticated session cookie. workspaceApiKey: type: http scheme: bearer bearerFormat: Workspace API key (cl_api_...) description: >- A workspace API key from Workspace settings > API keys. Creating a ticket needs a Full access key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.