Trigger API Reference

Learn how to use the template trigger API to process inputs with your templates.

# API Endpoint

The primary endpoint for triggering templates is:

POST https://okdata.app/api/trigger

# Request Parameters

The API accepts the following parameters:

Parameter	Type	Required	Description
templateId	string	Yes	The unique identifier of the template to trigger (e.g., AB1234)
text	string	Conditional*	Text input to process with the template
file	binary	Conditional*	File input (image, PDF, audio) to process
llm	string	No	Override the default AI model for this request (e.g., gpt-4o)
webhookUrl	string	No	URL to receive results asynchronously

* At least text or file must be provided, depending on what input types your template accepts.

# Request Examples

Text Input Example

Using the Geo Guesser template to identify a city from a text description:

curl -X POST https://okdata.app/api/trigger \
  -F "templateId=AB1234" \
  -F "text=the city holding the status of liberty"

File Input Example

Submitting an image file to the Geo Guesser template:

curl -X POST https://okdata.app/api/trigger \
  -F "templateId=AB1234" \
  -F "file=@/path/to/your/city-image.jpg"

# Response Format

The API returns a JSON response with the following structure:

{
  "data": {
    "city": "New York",
    "country": "USA",
    "currency": "USD",
    "isCapital": false,
    "population": "8.4 million"
  },
  "ai": {
    "llm": "openai:gpt-4o",       // Model used for processing
    "duration": 1207,             // Processing time in milliseconds
    "date": "2025-05-12T07:17:37.525Z" // Processing timestamp
  },
  "success": true                 // Status indicator
}

Response Fields:

data - Contains the structured output matching your template's schema
ai - Information about the AI processing (model, duration, timestamp)
success - Boolean indicator of whether the request was successful

# Error Handling

In case of an error, the API returns a JSON response with an error message:

{
  "error": "Template not found",
}

Error Code	Description
AUTHENTICATION_ERROR	Invalid or missing API key
TEMPLATE_NOT_FOUND	The specified template ID does not exist
INVALID_INPUT	Missing required input or input in wrong format
PROCESSING_ERROR	Error occurred during template processing
RATE_LIMIT_EXCEEDED	API rate limits exceeded

# Rate Limits

API usage is subject to rate limits based on your subscription plan. Current limits:

Free tier: 20 requests per day
Pro tier: 1,000 requests per day
Enterprise tier: Custom limits based on your agreement

# Best Practices

Error Handling

Always implement proper error handling in your integration to handle API errors and unexpected responses.

Rate Limiting

Implement backoff strategies for high-volume applications to handle potential rate limits.

Response Validation

Always validate the response structure before using it in your application.

Use Webhooks for Long-Running Tasks

For processes that may take longer, use the webhookUrl parameter to receive results asynchronously.

For any questions about the Trigger API, contact us at okdata.app@gmail.com.