Execute Agent

Execute an agent with custom variables.

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 (200)

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "agentId": "agent_123",
  "message": "Agent execution queued successfully"
}

Field	Type	Description
jobId	string	Unique execution ID - use to check status
status	string	queued | processing | completed | failed
agentId	string	Agent that was executed
message	string	Human-readable status message

Error Responses

Missing Variables (400)

{
  "error": "Missing required variables",
  "missingVariables": ["product_name", "features"]
}

Invalid API Key (401)

{
  "error": "Invalid or revoked API key"
}

Agent Not Found (404)

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

Rate Limit Exceeded (429)

{
  "error": "Rate limit exceeded",
  "retryAfter": 45,
  "rateLimits": {
    "requestsPerMinute": 100
  }
}

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 jobId to check status:

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

Learn more →

Next Steps

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