# Aria CRM API Reference
# For product overview: /llms.txt
# For complete product documentation, features, and data model: /llms-full.txt
# Base URL: https://your-domain.com
# Auth: Bearer token, Authorization: Bearer aria_sk_<token>
# Create API keys at Settings > API Keys in the web UI
# OpenAPI spec: /openapi.json

## Quick Start

```bash
# Set your API key
export API_KEY="aria_sk_..."

# List all object types
curl -H "Authorization: Bearer $API_KEY" https://your-domain.com/api/v1/objects

# List people records
curl -H "Authorization: Bearer $API_KEY" https://your-domain.com/api/v1/objects/people/records

# Create a person
curl -X POST https://your-domain.com/api/v1/objects/people/records \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"name": {"first_name": "Jane", "last_name": "Doe"}, "email_addresses": "jane@example.com"}}'

# Search across all records
curl -H "Authorization: Bearer $API_KEY" "https://your-domain.com/api/v1/search?q=Jane"

# Query with filters
curl -X POST https://your-domain.com/api/v1/objects/deals/records/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"operator": "and", "conditions": [{"attribute": "deal_value", "operator": "gte", "value": 10000}]}, "sorts": [{"attribute": "deal_value", "direction": "desc"}]}'
```

## Response Format

All responses use envelope format:
- Success: `{ "data": <payload> }`
- Error: `{ "error": { "code": "ERROR_CODE", "message": "description" } }`
- Paginated: `{ "data": { "records": [...], "pagination": { "limit": 50, "offset": 0, "total": 123 } } }`

## Endpoints

### Objects (schema types like People, Companies, Deals)
GET    /api/v1/objects                              : List all objects
POST   /api/v1/objects                              : Create object {slug, singularName, pluralName, icon?}
GET    /api/v1/objects/:slug                         : Get object with attributes
PATCH  /api/v1/objects/:slug                         : Update object
DELETE /api/v1/objects/:slug                         : Delete object (admin)

### Attributes (fields on objects)
GET    /api/v1/objects/:slug/attributes              : List attributes
POST   /api/v1/objects/:slug/attributes              : Create attribute {slug, title, type, config?, isRequired?, isUnique?, isMultiselect?, options?, statuses?}
PATCH  /api/v1/objects/:slug/attributes              : Update attribute {attributeId, ...fields}
DELETE /api/v1/objects/:slug/attributes?attributeId=  : Delete attribute

### Attribute Options (select/status values)
GET    /api/v1/objects/:slug/attributes/options?attributeId=  : List options
POST   /api/v1/objects/:slug/attributes/options              : Create option {attributeId, title, color?, isActive?}
PATCH  /api/v1/objects/:slug/attributes/options              : Update option {optionId, attributeType, ...fields}
DELETE /api/v1/objects/:slug/attributes/options?optionId=&attributeType=  : Delete option

### Records (data entries)
GET    /api/v1/objects/:slug/records?limit=50&offset=0       : List records (paginated)
POST   /api/v1/objects/:slug/records                          : Create record {values: {attr_slug: value}}
GET    /api/v1/objects/:slug/records/:recordId                : Get single record
PATCH  /api/v1/objects/:slug/records/:recordId                : Update record {values: {attr_slug: value}}
DELETE /api/v1/objects/:slug/records/:recordId                : Delete record

### Record Query (filter + sort)
POST   /api/v1/objects/:slug/records/query
  Body: {limit?, offset?, filter?: FilterGroup, sorts?: SortConfig[]}
  Filter: {operator: "and"|"or", conditions: [{attribute, operator, value}]}
  Operators: equals, not_equals, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty, gt, gte, lt, lte
  Sort: {attribute: "slug", direction: "asc"|"desc"}
  Assert mode: {mode: "assert", matchAttribute, matchValue, values}, find-or-create

### Record Relations & Activity
GET    /api/v1/objects/:slug/records/:recordId/related   : Related records (forward + inverse refs)
GET    /api/v1/objects/:slug/records/:recordId/activity  : Activity feed
GET    /api/v1/objects/:slug/records/:recordId/tasks     : Tasks linked to record
GET    /api/v1/objects/:slug/records/:recordId/notes     : Notes on record
POST   /api/v1/objects/:slug/records/:recordId/notes     : Create note {title?, content?}

### Bulk Import
POST   /api/v1/objects/:slug/records/import    : Import up to 1000 records {rows: [{attr_slug: value, ...}]}
  Response: {created, errors: [{row, message}], total}

### Lists (curated collections of records)
GET    /api/v1/lists                                     : List all lists
POST   /api/v1/lists                                     : Create list {name, objectSlug, isPrivate?}
GET    /api/v1/lists/:listId                              : Get list
PATCH  /api/v1/lists/:listId                              : Update list
DELETE /api/v1/lists/:listId                              : Delete list

### List Attributes
GET    /api/v1/lists/:listId/attributes                   : List list-specific attributes
POST   /api/v1/lists/:listId/attributes                   : Create list attribute {slug, title, type}
PATCH  /api/v1/lists/:listId/attributes                   : Update list attribute {id, ...fields}
DELETE /api/v1/lists/:listId/attributes?id=               : Delete list attribute

### List Entries
GET    /api/v1/lists/:listId/entries?limit=50&offset=0    : List entries (paginated)
POST   /api/v1/lists/:listId/entries                      : Add record to list {recordId, values?}
PATCH  /api/v1/lists/:listId/entries/:entryId             : Update entry values {values}
DELETE /api/v1/lists/:listId/entries/:entryId             : Remove entry from list
GET    /api/v1/lists/:listId/available-records?search=    : Records not in this list

### Notes
GET    /api/v1/notes?limit=50&offset=0                    : List all notes (paginated)
GET    /api/v1/notes/:noteId                              : Get note
PATCH  /api/v1/notes/:noteId                              : Update note {title?, content?}
DELETE /api/v1/notes/:noteId                              : Delete note

### Tasks
GET    /api/v1/tasks?showCompleted=false&limit=50&offset=0  : List tasks (paginated)
POST   /api/v1/tasks                                        : Create task {content, deadline?, recordIds?, assigneeIds?}
PATCH  /api/v1/tasks/:taskId                                : Update task {content?, isCompleted?, deadline?}
DELETE /api/v1/tasks/:taskId                                : Delete task

### Workspace
GET    /api/v1/workspace                                 : Get workspace
PATCH  /api/v1/workspace                                 : Update workspace (admin) {name?}

### Workspace Members
GET    /api/v1/workspace-members                         : List members
POST   /api/v1/workspace-members                         : Add member (admin) {email, role?}
PATCH  /api/v1/workspace-members/:memberId               : Update role (admin) {role}
DELETE /api/v1/workspace-members/:memberId               : Remove member (admin)

### Notifications
GET    /api/v1/notifications?unreadOnly=false&limit=30   : List notifications
PATCH  /api/v1/notifications/:notificationId             : Mark as read
POST   /api/v1/notifications/mark-all-read               : Mark all as read

### Search
GET    /api/v1/search?q=query&limit=20                   : Global search
GET    /api/v1/records/browse?limit=20                   : Browse recent records

### API Keys (admin only)
GET    /api/v1/api-keys                                  : List API keys
POST   /api/v1/api-keys                                  : Create key {name, scopes?, expiresAt?}
DELETE /api/v1/api-keys/:keyId                           : Revoke key

### AI Chat
POST   /api/v1/chat/completions                          : Stream AI response (SSE) {conversationId, message}
GET    /api/v1/chat/conversations                         : List conversations
POST   /api/v1/chat/conversations                         : Create conversation
GET    /api/v1/chat/conversations/:id                     : Get conversation with messages
DELETE /api/v1/chat/conversations/:id                     : Delete conversation
POST   /api/v1/chat/tool-confirm                          : Approve/reject AI write tool {toolCallId, approved}

### Dashboard & Analytics
GET    /api/v1/dashboard?view=rep|manager|leadership      : Pipeline dashboard data
POST   /api/v1/dashboard/preferences                      : Save view preference {view}
GET    /api/v1/activity-scores?limit=20                   : Activity-scored records (hot leads)
GET    /api/v1/analytics/win-loss                         : Win/loss pattern analysis
GET    /api/v1/analytics/rep-coaching                     : Rep coaching metrics
GET    /api/v1/analytics/forecast                         : Pipeline forecast
GET    /api/v1/analytics/next-best-action                 : AI next best action

### Reviews (AI Drafts + Approvals)
GET    /api/v1/assets?status=draft                        : List AI-generated drafts
GET    /api/v1/assets/:id                                 : Get asset detail
POST   /api/v1/assets/:id/approve                         : Approve AI draft
POST   /api/v1/assets/:id/reject                          : Reject AI draft
GET    /api/v1/approvals/requests?status=pending           : List approval requests
POST   /api/v1/approvals/requests                          : Create approval request
GET    /api/v1/approvals/requests/:id                      : Get approval request
POST   /api/v1/approvals/requests/:id/approve              : Approve {note?}
POST   /api/v1/approvals/requests/:id/reject               : Reject {note?}
GET    /api/v1/approvals/rules                             : List approval rules
POST   /api/v1/approvals/rules                             : Create approval rule
PUT    /api/v1/approvals/rules/:id                         : Update approval rule
DELETE /api/v1/approvals/rules/:id                         : Delete approval rule

### Sales Tools
GET    /api/v1/sequences                                  : List sequences
POST   /api/v1/sequences                                  : Create sequence {name, description?}
GET    /api/v1/sequences/:id                              : Get sequence
PATCH  /api/v1/sequences/:id                              : Update sequence
DELETE /api/v1/sequences/:id                              : Delete sequence
POST   /api/v1/sequences/:id/steps                        : Add step to sequence
POST   /api/v1/sequences/:id/enrollments                  : Enroll contacts {recordIds}
GET    /api/v1/battlecards                                : List battlecards

### Close (Contracts + Handoff)
GET    /api/v1/contracts                                  : List contracts
POST   /api/v1/contracts                                  : Create contract {title, contractType, routeToApproval?}
GET    /api/v1/contracts/:id                              : Get contract
PATCH  /api/v1/contracts/:id                              : Update contract {status}
GET    /api/v1/contracts/:id/download                     : Download contract
GET    /api/v1/contracts/templates                        : List templates
POST   /api/v1/contracts/templates                        : Create template
GET    /api/v1/close-flow/handoff                         : List handoff briefs
POST   /api/v1/close-flow/handoff                         : Create handoff brief
POST   /api/v1/close-flow/handoff/:id/deliver             : Deliver via webhook {webhookUrl}

### Automations
GET    /api/v1/automations                                : List automation rules
POST   /api/v1/automations                                : Create rule {name, triggerType, triggerConfig, actionType, actionConfig, enabled}
GET    /api/v1/automations/:id                            : Get rule
PATCH  /api/v1/automations/:id                            : Update rule
DELETE /api/v1/automations/:id                            : Delete rule

### Webhooks
GET    /api/v1/webhooks                                   : List outbound webhooks
POST   /api/v1/webhooks                                   : Create webhook {name, url, events[], secret?}
PATCH  /api/v1/webhooks/:id                               : Update webhook {enabled?, events?}
DELETE /api/v1/webhooks/:id                               : Delete webhook
POST   /api/v1/webhooks/:id/test                          : Send test ping

### AI Settings
GET    /api/v1/ai-settings                                : Get AI config (OpenRouter)
PATCH  /api/v1/ai-settings                                : Update AI config {apiKey?, model?}
POST   /api/v1/ai-settings/test                           : Test AI connection

### Timeline
GET    /api/v1/timeline/:recordId                         : Record activity timeline

## Value Formats by Attribute Type

When setting record values, use these formats:

| Type | Format | Example |
|------|--------|---------|
| text | string | `"Hello world"` |
| number | number | `42` |
| currency | number | `99.99` |
| date | ISO date string | `"2025-01-15"` |
| timestamp | ISO datetime | `"2025-01-15T10:30:00Z"` |
| checkbox | boolean | `true` |
| select | option title string | `"High Priority"` |
| status | status title string | `"In Progress"` |
| rating | integer 1-5 | `4` |
| email_address | email string | `"user@example.com"` |
| phone_number | string | `"+1-555-0123"` |
| domain | URL/domain string | `"example.com"` |
| location | string | `"San Francisco, CA"` |
| personal_name | object | `{"first_name": "Jane", "last_name": "Doe"}` |
| record_reference | record UUID | `"uuid-of-target-record"` |
| actor_reference | user UUID | `"uuid-of-user"` |
| interaction | object | `{"type": "email", "subject": "Re: Deal"}` |

## Common Patterns

### Create a company and link a person to it
```bash
# 1. Create company
COMPANY=$(curl -s -X POST .../api/v1/objects/companies/records \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"name": "Acme Inc", "domains": "acme.com"}}')
COMPANY_ID=$(echo $COMPANY | jq -r '.data.id')

# 2. Create person linked to company
curl -X POST .../api/v1/objects/people/records \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"values\": {\"name\": {\"first_name\": \"John\", \"last_name\": \"Smith\"}, \"company\": \"$COMPANY_ID\"}}"
```

### Find or create (assert mode)
```bash
curl -X POST .../api/v1/objects/companies/records/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "assert", "matchAttribute": "domains", "matchValue": "acme.com", "values": {"name": "Acme Inc"}}'
```

### Paginate through all records
```bash
OFFSET=0
while true; do
  RESULT=$(curl -s ".../api/v1/objects/people/records?limit=200&offset=$OFFSET" \
    -H "Authorization: Bearer $API_KEY")
  COUNT=$(echo $RESULT | jq '.data.records | length')
  [ "$COUNT" -eq 0 ] && break
  # Process records...
  OFFSET=$((OFFSET + 200))
done
```

## Error Codes
| Code | HTTP | Meaning |
|------|------|---------|
| UNAUTHORIZED | 401 | Missing or invalid auth |
| FORBIDDEN | 403 | Insufficient permissions (admin required) |
| NOT_FOUND | 404 | Resource not found |
| BAD_REQUEST | 400 | Invalid input |
| INTERNAL_ERROR | 500 | Server error |

## Rate Limits
No rate limits enforced (self-hosted). Be reasonable with bulk operations.

## Notes
- All IDs are UUIDs
- Timestamps are ISO 8601 format
- Pagination defaults: limit=50, offset=0 (max limit varies by endpoint, usually 200)
- Admin-only endpoints: DELETE objects, workspace updates, member management, API key management
- The API uses a typed EAV (Entity-Attribute-Value) data model, records store values per-attribute