Overview
Get started
Create an API key, then ask Phil your first question over HTTPS. Keys belong to your workspace and every request is tracked on the Usage page.
Quickstart
Base URL:
Playground
Runs the same request the API runs, and it counts on the Usage page like any API call.
API keys
A key is shown once, at creation. Store it server side and never in a browser or repository.
| Name | Key | Created | Last used | Status |
|---|
No keys yet. Create your first key to call the API.
Usage
Requests per day
By credential
| Credential | Requests | Input tokens | Output tokens | Last used |
|---|
Limits
Limits apply per key. During the beta the API is included with the Agent plan, with no separate API billing.
| Limit | Value | What happens at the limit |
|---|---|---|
| Full Phil requests per hour (/chat) | 100 | The API answers 429. Wait for the next hour window. |
| Document requests per hour (/ask) | 300 | The API answers 429. Wait for the next hour window. |
| Concurrent requests | 4 | The API answers 429. Finish an in-flight request first. |
| Active keys per workspace | 10 | Key creation is refused until one is revoked. |
| Request body | 16 KB | The API answers 413. |
| Answer deadline | 90 seconds | The request fails and does not count against your answer. |
Documentation
Three endpoints. Authenticate every request with your key in the Authorization header. The API is server to server: requests carrying browser cookies are refused.
POST /agent/v1/chat
Full Phil: he decides for himself whether to search live listings, run web research on Australian sources, pull suburb data, or read your documents on the way to his reply. Stateless: pass your own conversation history each call.
Body
| Field | Type | Notes |
|---|---|---|
message | string | Required. Up to 4000 characters. |
clientRequestId | string | Required. Your unique id for this request; retries with the same id never run the work twice. |
history | array | Optional. Up to 12 turns of {"role": "user" | "assistant", "content": "..."}. |
Response
{
"reply": "...",
"intent": "SEARCH",
"listings": 6,
"usage": { "inputTokens": 9120, "outputTokens": 640 },
"agentRequestId": "areq_..."
}
POST /agent/v1/ask
Ask Phil a question grounded in your workspace documents. Phil answers with citations, or abstains when the documents do not cover it.
Body
| Field | Type | Notes |
|---|---|---|
question | string | Required. The question to answer. |
clientRequestId | string | Required. Your unique id for this request. Retrying with the same id never runs the work twice. |
collectionIds | string[] | Optional. Restrict the answer to these sources. |
Response
{
"answer": "...",
"abstained": false,
"citations": [{ "documentId": "...", "title": "...", "evidenceId": "..." }],
"usage": { "inputTokens": 812, "outputTokens": 214 },
"agentRequestId": "areq_..."
}
GET /agent/v1/documents
List the documents your key can see. Cursor paginated.
GET /agent/v1/health
Your workspace's API health: active grants, connector state, and source counts.
Errors
| Status | Meaning |
|---|---|
| 401 | The key is missing, wrong, revoked, or expired. |
| 403 | The key or workspace is not allowed to do this. |
| 409 | The same clientRequestId was reused with a different question. |
| 413 | The request body is over 16 KB. |
| 429 | Rate limited. Slow down and retry later. |
| 502 | Phil could not produce an answer. Safe to retry with the same clientRequestId. |