Execute Agent

Execute an agent with custom variables. Execution runs asynchronously; this endpoint returns immediately with an executionId you can poll for status.

Endpoint

POST /api/v1/agents/{agentId}/execute

Authentication

Requires API key in Authorization header:

Authorization: Bearer pk_live_YOUR_API_KEY

Request Body

{
  "variables": {
    "variable_name": "value",
    "another_variable": "another value"
  }
}

Parameters

Field	Type	Required	Description
variables	object	Yes	Key-value pairs of variables required by the agent

Response

Success (202 Accepted)

{
  "success": true,
  "executionId": "550e8400-e29b-41d4-a716-446655440000",
  "agentId": "agent_123",
  "agentName": "Product Description Generator",
  "status": "processing",
  "message": "Agent execution started",
  "statusUrl": "/api/v1/agents/agent_123/executions/550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
success	boolean	Always true on success
executionId	string	Unique execution ID — use to check status
agentId	string	Agent that was executed
agentName	string	Human-readable agent name
status	string	Initial status — always "processing" on a 202
message	string	Human-readable status message
statusUrl	string	Relative URL for polling execution status

Error Responses

Missing Variables (400)

{
  "error": "Missing required variables",
  "message": "The following variables are required",
  "missingVariables": ["product_name", "features"],
  "requiredVariables": ["product_name", "features", "tone"]
}

Invalid API Key (401)

{
  "error": "Invalid or revoked API key",
  "message": "The provided API key is not valid for this agent"
}

Agent Not Found (404)

{
  "error": "Agent not found",
  "message": "Agent agent_123 does not exist"
}

Rate Limit Exceeded (429)

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "rateLimits": {
    "requestsPerMinute": 10,
    "requestsPerHour": 100,
    "requestsPerDay": 1000
  }
}

The rateLimits object reflects the limits configured on the API key that hit the cap.

Example Request

curl -X POST https://api.promptick.ai/api/v1/agents/agent_abc123/execute \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "product_name": "Smart Watch Pro",
      "target_audience": "fitness enthusiasts",
      "tone": "energetic"
    }
  }'

Checking Execution Status

Use the returned executionId to poll for results:

GET /api/v1/agents/{agentId}/executions/{executionId}

Learn more →

Next Steps

• Check Status - Poll for results
• Code Examples - Integration samples