API triggers

API triggers let external systems request documentation updates from Promptless. Connect your CI/CD pipelines, custom automation tools, or any system that can make HTTP requests.

Use cases

API triggers work well when you want to:

• Integrate Promptless into CI/CD pipelines that run after deployments
• Build custom automation workflows that trigger documentation updates
• Connect external systems (ticketing, project management, custom tools) to Promptless
• Programmatically request documentation updates without using Slack or the dashboard

Set up API triggers

API triggers are a built-in trigger type that’s always active when an API key exists, no YAML configuration required.

Generate an API key

API keys are managed in your organization’s Settings page.

1. Navigate to Settings > API Access
2. Click Generate Key to create a new API key
3. Copy the key immediately—it’s only shown once

Warning

Store your API key securely. The full key is only displayed when first generated. Promptless stores only a hash of the key for validation.

Key management

• One active key per organization: Each organization can have one active API key at a time
• Key rotation: Generating a new key immediately revokes the previous key
• Revocation: You can revoke your active key at any time from the Settings page

Tip

When rotating keys, update your integrations before generating a new key. The previous key stops working immediately when you create a new one.

Use the API

For the full request and response schemas, status codes, and an interactive explorer, see the API Reference. The sections below cover the same endpoint with examples.

Endpoint

POST /triggers

Authentication

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer sk-pl-your-api-key

The bearer token determines which organization receives the trigger—no need to specify an organization ID in the URL.

Request format

Send a JSON body with your documentation instructions:

{
  "instructions": "Update the getting started guide with the new authentication flow",
  "context": {
    "ticket_id": "ENG-123",
    "requested_by": "deploy-bot"
  }
}

Field	Type	Required	Description
instructions	string	Yes	What you want Promptless to document. Be specific about which docs to update and what changes to make.
context	object	No	Additional metadata to include with the request. This appears in trigger history for reference.

Example request

curl -X POST "https://api.gopromptless.ai/triggers" \
  -H "Authorization: Bearer sk-pl-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Document the new rate limiting feature added in v2.5",
    "context": {
      "release": "v2.5.0",
      "jira_ticket": "DOC-456"
    }
  }'

Response

A successful request returns a 202 Accepted response:

{
  "trigger_event_id": "abc123-..."
}

Error responses

Status	Error	Description
401	authentication_failed	The API key is missing, invalid, or revoked.
409	org_not_configured	Your organization hasn’t finished setting up Promptless.
409	no_eligible_doc_collection	The requested doc collection is not configured or not ready.
422	Validation error	The request body is invalid.
500	enqueue_failed	The trigger could not be enqueued for processing.
503	runtime_store_unavailable	Trigger intake is temporarily unavailable.

View API triggers

API-triggered events appear in your dashboard with a distinct “API” label.

Trigger history

View all API triggers on the Triggers page. API triggers show the submitted instructions and any context you included in the request.

Change history

Filter by “API” source in Change History to see documentation suggestions that came from API requests.

How it works

When you submit an API request:

1. Validation: Promptless validates your API key and request format.
2. Routing: The request is routed to your configured doc collections.
3. Processing: Promptless analyzes your instructions along with configured context sources.
4. Suggestion Creation: If documentation updates are needed, Promptless creates suggestions.

Note

API triggers use the same processing pipeline as other trigger types. The suggestions appear in your dashboard and follow your configured publishing policies.