API Reference

Complete reference for Phoenix's REST API endpoints and how to interact with your purchased agents.

Base URL

https://your-phoenix-instance.vercel.app/api

Agent Service API

Note: To use the Agent Service API, you must first purchase an agent. Each purchased agent gets a unique agent ID that you use in the API endpoint.

Interact with Your Agent

POST

/api/service/{agent_id}

Endpoint Structure

POST https://your-phoenix-instance.vercel.app/api/service/QmaXcMfG

Replace QmaXcMfG with your actual agent ID received after purchase.

Request Headers

Content-Type: application/json

Request Body

{
  "query": "What can u do?"
}

Response Format

{
  "result": "I can generate images based on text prompts using the 'generateImage' function. For example, if you provide the prompt 'a cat riding a bicycle', I will generate an image of a cat riding a bicycle.",
  "tools": [
    {
      "stepType": "initial",
      "text": "I can generate images based on text prompts using the 'generateImage' function. For example, if you provide the prompt 'a cat riding a bicycle', I will generate an image of a cat riding a bicycle.",
      "reasoningDetails": [],
      "files": [],
      "sources": [],
      "toolCalls": []
    }
  ]
}

Response Fields

result

The main response text from your agent

tools

Array of tool execution steps and details

stepType

Type of step (initial, tool_call, etc.)

text

Text content for this step

reasoningDetails

Agent's reasoning process (if available)

files

Generated or processed files

sources

Information sources used

toolCalls

Details of tools executed

Example Usage

cURL Example

curl -X POST https://your-phoenix-instance.vercel.app/api/service/QmaXcMfG \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Generate an image of a sunset over mountains"
  }'

JavaScript Example

const response = await fetch('https://your-phoenix-instance.vercel.app/api/service/QmaXcMfG', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'What are your capabilities?'
  })
});

const data = await response.json();
console.log(data.result);

Error Handling

HTTP Status Codes

200Success - Agent responded successfully

400Bad Request - Invalid query format

401

403Forbidden - Agent not purchased or access denied

404Not Found - Agent ID does not exist

429Rate Limited - Too many requests

500Internal Server Error - Agent processing failed

Rate Limits

API Usage Limits

Understand the limits for your API usage

100

Requests per minute

1000

Requests per hour

10000

Requests per day

Rate limits may vary based on your subscription plan. Contact support for higher limits.

Best Practices

Optimization Tips

Query Optimization

• Be specific and clear in your queries
• Provide context when necessary
• Break complex requests into smaller parts
• Use consistent terminology

Error Handling

• Always check response status codes
• Implement retry logic for transient errors
• Log errors for debugging
• Handle rate limiting gracefully

Security

• Never expose API keys in client-side code
• Use environment variables for API keys
• Rotate API keys regularly
• Monitor API usage for anomalies