APIs
Ticket Form API
Reference

API - Ticket Form - Reference

GET /ticket-forms/

Get all ticket forms associated with the user.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/ticket-forms \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": [
    {
      "id": "f162e570-4952-465b-ad74-2a9e14518998",
      "public_id": "Aj96xCSIxAbsLhK5gb4Y1",
      "title": "Test Form",
      "allowed_domains": [
        "www.mywebsite.com",
        "app.mywebsite.com"
      ],
      "fields": [
        {
          "name": "What is your name?",
          "id": "d4qdd",
          "type": "TEXT",
          "required": true
        },
        {
          "name": "What do you work with?",
          "defaultSelectValues": [
            {
              "value": "ops-wxr",
              "label": "Ops"
            },
            {
              "value": "leadership-v38",
              "label": "Leadership"
            },
          ],
          "id": "y20j7",
          "type": "MULTI_SELECT",
          "required": true
        },
        ...
      ]
    },
    ...
  ]
}

GET /ticket-form/:id/

Get a specific ticket form by ID.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/ticket-form/Aj96xCSIxAbsLhK5gb4Y1 \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
      "id": "f162e570-4952-465b-ad74-2a9e14518998",
      "public_id": "Aj96xCSIxAbsLhK5gb4Y1",
      "title": "Test Form",
      "allowed_domains": [
        "www.mywebsite.com",
        "app.mywebsite.com"
      ],
      "fields": [
        {
          "name": "What is your name?",
          "id": "d4qdd",
          "type": "TEXT",
          "required": true
        },
        {
          "name": "What do you work with?",
          "defaultSelectValues": [
            {
              "value": "ops-wxr",
              "label": "Ops"
            },
            {
              "value": "leadership-v38",
              "label": "Leadership"
            },
          ],
          "id": "y20j7",
          "type": "MULTI_SELECT",
          "required": true
        },
        ...
      ]
    }
}

GET /ticket-form/:id/knowledge

Get all knowledge items associated with a ticket form.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/ticket-form/thcGFWKP4_XhwOC7ohwAQ/knowledge \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "24019214-f4ea-417b-9741-e13bc3b6c471",
        "type": "website",
        "base_url": "https://www.mywebsite.com/",
        "trained_at": "2023-12-24T06:05:17.365Z",
        "is_training": false,
        "training_failed_at": null,
        "training_failed_with": null
      },
      ...
    ],
    "total": 40,
    "has_more": true,
    "next_cursor": "MjUuNTA="
  }
}

PUT /ticket-form/:id/knowledge

Add a new knowledge item to a ticket-form.

ℹ️

The knowledge item must have a trained model.
The model can be trained using the /knowledge/:id/train endpoint.

Example request

curl --request PUT \
 --url https://api.aidbase.ai/v1/ticket-form/thcGFWKP4_XhwOC7ohwAQ/knowledge \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --data '{
    "knowledge_id": "24019214-f4ea-417b-9741-e13bc3b6c471"
 }'

Example response

{
  "success": true,
}

DELETE /ticket-form/:id/knowledge

Remove a knowledge item from a ticket form.

ℹ️

The knowledge item will be removed from the ticket form, but the knowledge item itself will not be deleted.

Example request

curl --request DELETE \
 --url https://api.aidbase.ai/v1/ticket-form/thcGFWKP4_XhwOC7ohwAQ/knowledge \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --data '{
    "knowledge_id": "24019214-f4ea-417b-9741-e13bc3b6c471"
 }'

Example response

{
  "success": true,
}

GET /ticket-form/:id/tickets

Get all tickets associated with a ticket form.

Query Parameters

ParameterTypeDescription
statusstring (optional)Comma-separated list of ticket statuses to filter by (e.g., open,assigned,closed). Values are trimmed and case-insensitive. Returns HTTP 400 if empty or contains invalid status values.
created_beforestring (optional)Filter tickets created before this timestamp. Accepts ISO 8601 date-time strings or any parsable date format (e.g., 2026-02-01T00:00:00Z or 2026-02-01). Returns HTTP 400 if the date format is invalid.
created_afterstring (optional)Filter tickets created after this timestamp. Accepts ISO 8601 date-time strings or any parsable date format (e.g., 2026-01-01T00:00:00Z or 2026-01-01). Returns HTTP 400 if the date format is invalid.
ℹ️

Filters are applied before pagination. The total count in the response reflects the filtered results.

Example request

curl --request GET \
 --url 'https://api.aidbase.ai/v1/ticket-form/Aj96xCSIxAbsLhK5gb4Y1/tickets?status=open,assigned&created_after=2026-01-01T00:00:00Z&created_before=2026-02-01T00:00:00Z' \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "e5c9d8a6-1f53-4e3c-8d5f-9a7b8c6d5e4f",
        "status": "open",
        "created_at": "2024-01-16T09:20:00.000Z",
        "updated_at": "2024-01-16T09:20:00.000Z"
      },
      {
        "id": "f6d0e9b7-2g64-5f4d-9e6g-0b8c9d7e6f5g",
        "status": "closed",
        "created_at": "2024-01-15T14:30:00.000Z",
        "updated_at": "2024-01-15T16:45:00.000Z"
      },
      ...
    ],
    "total": 230,
    "has_more": true,
    "next_cursor": "MjUuNTA="
  }
}

GET /ticket-form/:id/tickets/:id

Get a specific ticket by ID.

Example request

curl --request GET \
 --url https://api.aidbase.ai/v1/ticket-form/Aj96xCSIxAbsLhK5gb4Y1/tickets/e5c9d8a6-1f53-4e3c-8d5f-9a7b8c6d5e4f \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "id": "e5c9d8a6-1f53-4e3c-8d5f-9a7b8c6d5e4f",
    "status": "open",
    "created_at": "2024-01-16T09:20:00.000Z",
    "updated_at": "2024-01-16T09:20:00.000Z",
    "conversation": [
      {
        "role": "user",
        "message": "I'm having trouble logging into my account."
      },
      {
        "role": "assistant",
        "message": "I'd be happy to help you with that. Can you provide your email address?"
      },
      {
        "role": "user",
        "message": "My email is user@example.com"
      },
      {
        "role": "assistant",
        "message": "Thank you. I've sent a password reset link to your email."
      }
    ]
  }
}

PUT /ticket-form/:id/tickets/:id/block

Block a specific ticket, preventing further interaction from the user associated with that ticket.

ℹ️

This endpoint requires the TICKETFORMS_WRITE scope.

Example request

curl --request PUT \
 --url https://api.aidbase.ai/v1/ticket-form/Aj96xCSIxAbsLhK5gb4Y1/tickets/e5c9d8a6-1f53-4e3c-8d5f-9a7b8c6d5e4f/block \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]'

Example response

{
  "success": true,
  "data": {
    "items": [
      {
        "target": "e5c9d8a6-1f53-4e3c-8d5f-9a7b8c6d5e4f",
        "targetType": "TICKET",
        "status": "ACTIVE"
      }
    ],
    "failed": []
  }
}

Error cases

StatusErrorDescription
400Bad RequestFailed to block the ticket.
401UnauthorizedInvalid or missing API key.
403ForbiddenAPI key is missing the `TICKETFORMS_WRITE` scope, or the ticket form does not belong to the account.
404Not FoundTicket form or ticket not found.

PUT /ticket-form/:id/tickets/:id

Update the status and/or priority of a specific ticket. The change behaves identically to updating a ticket through the Aidbase app, including full history tracking and any associated side effects.

ℹ️

This endpoint requires the TICKETS_WRITE scope.

Request body

FieldTypeDescription
statusstring (optional)The new status to assign to the ticket. Must be one of: open, assigned, need_more_info, resolved, closed.
prioritystring (optional)The new priority to assign to the ticket (e.g., low, medium, high).
⚠️

The request body may only include status and/or priority, and must include at least one of them. Any additional fields will result in an HTTP 400 error. Invalid values for status or priority will also return HTTP 400.

Example request

curl --request PUT \
 --url https://api.aidbase.ai/v1/ticket-form/Aj96xCSIxAbsLhK5gb4Y1/tickets/e5c9d8a6-1f53-4e3c-8d5f-9a7b8c6d5e4f \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --header 'Content-Type: application/json' \
 --data '{
    "status": "closed"
 }'

Example response

{
  "success": true
}

Error cases

StatusErrorDescription
400Bad RequestMissing or invalid update fields, invalid `status` or `priority`, extra fields in the request body, or invalid/missing path IDs.
401UnauthorizedInvalid or missing API key.
403ForbiddenAPI key is missing the `TICKETS_WRITE` scope, or the ticket form does not belong to the account.
404Not FoundTicket form or ticket not found.

POST /ticket-form/:id/tickets/:id/reply

Reply to a ticket on behalf of the ticket form owner.

ℹ️

This endpoint requires the TICKETS_WRITE scope.

Request body

FieldTypeDescription
messagestring (required)The reply message to send to the ticket.
persona_idstring (optional)The ID of the persona to use as the sender. If omitted, the account username and profile image are used. Returns HTTP 400 if the provided ID is invalid or does not belong to the account.

Example request

curl --request POST \
 --url https://api.aidbase.ai/v1/ticket-form/Aj96xCSIxAbsLhK5gb4Y1/tickets/e5c9d8a6-1f53-4e3c-8d5f-9a7b8c6d5e4f/reply \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer [YOUR_API_KEY]' \
 --header 'Content-Type: application/json' \
 --data '{
    "message": "Thank you for reaching out. We are looking into your issue."
 }'

Example response

{
  "success": true
}

Error cases

StatusErrorDescription
400Bad RequestMissing `message`, invalid or missing path IDs, or `persona_id` is provided but is invalid or not owned by the account.
401UnauthorizedInvalid or missing API key.
403ForbiddenAPI key is missing the `TICKETS_WRITE` scope, or the ticket form does not belong to the account.
404Not FoundTicket form or ticket not found.
ReferenceReference
Aidbase Docs © 2026