Submit an API trigger

POST

/triggers

curl --request POST \
  --url https://api.gopromptless.ai/triggers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "instructions": "Document the new rate limiting feature added in v2.5", "context": { "jira_ticket": "DOC-456", "release": "v2.5.0" } }'

Request a documentation update. Authenticate with your organization’s API key as a bearer token. A successful request returns the identifier of the trigger event.

Download the OpenAPI spec (YAML)

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

ApiTriggerIntakeRequest

JSON request body for API-triggered task intake.

object

instructions

required

Instructions

What you want Promptless to document. Be specific about which docs to update and what changes to make.

string

>= 1 characters

context

Context

Optional arbitrary metadata to attach to the request. Appears in trigger history for reference and is passed through to the workflow as additional context.

object

key

additional properties

any

Responses

202

The trigger was accepted and enqueued for processing.

Media typeapplication/json

ApiTriggerAcceptedResponse

Response body returned when an API trigger is accepted for processing.

object

trigger_event_id

required

Trigger Event Id

Identifier of the trigger event. Use it to correlate with trigger history.

string

Example

{
  "trigger_event_id": "550e8400-e29b-41d4-a716-446655440000"
}

401

The API key is missing, invalid, or revoked.

Media typeapplication/json

ApiTriggerErrorResponse

Error body returned when an API trigger request is rejected.

object

error

required

Error

Stable machine-readable error code.

string

message

required

Message

Human-readable explanation of the error.

string

Example

{
  "error": "authentication_failed",
  "message": "Authentication failed."
}

409

The organization has not finished setting up Promptless (org_not_configured), or the requested doc collection is not configured or not ready (no_eligible_doc_collection).

Media typeapplication/json

ApiTriggerErrorResponse

Error body returned when an API trigger request is rejected.

object

error

required

Error

Stable machine-readable error code.

string

message

required

Message

Human-readable explanation of the error.

string

Example

{
  "error": "authentication_failed",
  "message": "Authentication failed."
}

422

The request body is invalid (e.g. empty instructions or a malformed UUID).

Media typeapplication/json

HTTPValidationError

Validation error body returned when the request fails schema validation.

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}

500

The trigger could not be enqueued for processing (enqueue_failed).

Media typeapplication/json

ApiTriggerErrorResponse

Error body returned when an API trigger request is rejected.

object

error

required

Error

Stable machine-readable error code.

string

message

required

Message

Human-readable explanation of the error.

string

Example

{
  "error": "authentication_failed",
  "message": "Authentication failed."
}

503

Trigger intake is temporarily unavailable (runtime_store_unavailable).

Media typeapplication/json

ApiTriggerErrorResponse

Error body returned when an API trigger request is rejected.

object

error

required

Error

Stable machine-readable error code.

string

message

required

Message

Human-readable explanation of the error.

string

Example

{
  "error": "authentication_failed",
  "message": "Authentication failed."
}