Getting Started

Start building with the PILOT API in under 5 minutes.

Quick Start

Get your API key

Your key will look like: pk_live_a1b2c3d4e5f6...

Important: The full API key is only shown once at creation. Copy it immediately and store it securely.

Make your first API call

Test your key by fetching your profile:

# Verify your API key
curl -H "Authorization: Bearer pk_live_YOUR_KEY" \
  https://app.withpilot.ai/api/v1/auth/me

Expected response:

{
  "id": "usr_abc123",
  "email": "you@company.com",
  "name": "Your Name",
  "role": "user"
}

Capture something

Send your first capture — PILOT will classify it automatically:

curl -X POST https://app.withpilot.ai/api/v1/capture \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Need to review the Q3 proposal before Friday meeting with Jaime",
    "source": "api"
  }'

PILOT classifies the input and returns:

{
  "id": "cap_xyz789",
  "content": "Need to review the Q3 proposal before Friday meeting with Jaime",
  "classification": "task",
  "confidence": 0.94,
  "extracted": {
    "title": "Review Q3 proposal for Friday meeting with Jaime",
    "person": "Jaime",
    "due_hint": "Friday"
  }
}

Get your daily briefing

curl -H "Authorization: Bearer pk_live_YOUR_KEY" \
  https://app.withpilot.ai/api/v1/briefing

Authentication

PILOT supports two authentication methods:

API Keys (recommended for integrations)

API keys are prefixed with pk_ and passed in the Authorization header:

Authorization: Bearer pk_live_your_key_here

Manage keys programmatically:

Action	Endpoint	Method
List keys	`GET /api/v1/keys`	GET
Create key	`POST /api/v1/keys`	POST
Revoke key	`DELETE /api/v1/keys/{key_id}`	DELETE

OAuth 2.0 (for user-facing apps)

For applications that act on behalf of a user, use the OAuth flow:

Redirect user to GET /api/v1/auth/oauth/start
User authenticates with Microsoft identity platform
Callback returns an authorization code
Exchange code at POST /api/v1/auth/oauth/callback for a JWT
Use JWT in Authorization header: Bearer eyJ...

Base URL

https://app.withpilot.ai

All API paths are relative to this base URL. The API version is embedded in the path: /api/v1/.

Rate Limits

Tier	Limit	Window
Standard (OAuth)	60 requests	Per minute
API Key	120 requests	Per minute

Rate limit info is returned in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When rate limited, you'll receive a 429 Too Many Requests response. Back off and retry after the reset time.

Error Handling

All errors follow a consistent format:

{
  "detail": "Human-readable error message",
  "status_code": 422
}

Common status codes

Code	Meaning	Action
`200`	Success	Request completed
`401`	Unauthorized	Check your API key or refresh your token
`403`	Forbidden	Your account lacks permission for this action
`404`	Not Found	Resource doesn't exist or wrong ID
`422`	Validation Error	Check request body against the schema
`429`	Rate Limited	Wait for `X-RateLimit-Reset` then retry
`500`	Server Error	Retry with exponential backoff. Contact support if persistent.

What's Next?

Full API Reference — All 90+ endpoints with schemas and examples
Email Triage Guide — Set up AI-powered email prioritization
Chat API Guide — Build conversational experiences with PILOT
Webhooks — Get notified when things happen (coming soon)

Need help? Contact us at support@withpilot.ai or visit withpilot.ai.