# Cortex User API

> Cortex is the social intelligence engine built by Nativz (nativz.io). This file is the complete machine-readable reference for the user-facing API surface: topic search, clients, and post scheduling.

Base URL: https://cortex.nativz.io
Docs: https://cortex.nativz.io/docs

## Authentication

All requests require a user API key, created in Settings -> API keys at https://cortex.nativz.io/settings/api-keys after logging in:

```
Authorization: Bearer ntvz_your_key_here
```

Keys start with ntvz_ and only ever see the clients your account can access. API access is enabled per organization by your Nativz team; if you can't create a key, contact your account manager.
Rate limit: 30 requests/minute per key. 429 responses include Retry-After (seconds).
Errors: { "error": string } with a matching HTTP status.
Dates are ISO 8601.

## MCP server

Cortex also ships an MCP server for AI assistants (Claude, ChatGPT, Cursor, Codex):

```
https://cortex.nativz.io/api/mcp/user
```

Transport: streamable HTTP. Auth: OAuth (sign in) or an ntvz_ key in the Authorization header.

## Topic search

### POST /api/v1/search

Queue a topic search for a client. The search is created in "pending" status and lands in the Cortex app for a Nativz teammate to run; completed research is reviewed in the Cortex app. There is no v1 endpoint that returns results.

Request body:
```
client_id - Client UUID (required)
query - Search query string (required)
search_mode - 'quick' | 'deep' (default 'quick')
```

Response:
```
{ "search": { "id", "query", "status", "search_mode", "created_at" } }
```

Example:
```
curl -X POST https://cortex.nativz.io/api/v1/search \
  -H "Authorization: Bearer ntvz_xxx" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"1f2e3d4c-5b6a-7c8d-9e0f-1a2b3c4d5e6f","query":"sustainable coffee trends","search_mode":"deep"}'
```

### GET /api/v1/search

Usage hint only. This path does not list searches; it returns 405 Method Not Allowed with { "error": "Use POST to trigger a search" }. Use POST /api/v1/search to queue a search.

Response:
```
405 Method Not Allowed
{ "error": "Use POST to trigger a search" }
```

Example:
```
curl https://cortex.nativz.io/api/v1/search \
  -H "Authorization: Bearer ntvz_xxx"
```

## Clients

### GET /api/v1/clients

List the clients your key can access. Returns a summary projection (no sensitive fields).

Response:
```
{ "clients": [ { "id", "name", "slug", "agency", "services", "health_score", "is_active", "industry", "website_url", "logo_url" } ] }
```

Example:
```
curl https://cortex.nativz.io/api/v1/clients \
  -H "Authorization: Bearer ntvz_xxx"
```

### GET /api/v1/clients/:id

Fetch a single client by UUID or slug, with its contacts.

Path parameter:
```
id - Client UUID or slug
```

Response:
```
{ "client": { "id", "name", "slug", "industry", "organization_id", "logo_url", "website_url", "target_audience", "brand_voice", "topic_keywords", "is_active", "health_score", "agency", "services", "description" }, "contacts": [ { "id", "full_name", "email", "phone", "role", "is_primary" } ] }
```

Example:
```
curl https://cortex.nativz.io/api/v1/clients/acme-coffee \
  -H "Authorization: Bearer ntvz_xxx"
```

## Posts

### GET /api/v1/posts

List scheduled posts for a client, ordered by scheduled_at ascending (nulls last). Optionally filtered by status.

Query parameters:
```
client_id - Client UUID (required)
status - Filter by post status: 'draft' | 'scheduled' | 'published' (optional)
```

Response:
```
{ "posts": [ { "id", "client_id", "caption", "hashtags", "scheduled_at", "status", "post_type", "created_at" } ] }
```

Example:
```
curl "https://cortex.nativz.io/api/v1/posts?client_id=1f2e3d4c-5b6a-7c8d-9e0f-1a2b3c4d5e6f&status=scheduled" \
  -H "Authorization: Bearer ntvz_xxx"
```

### GET /api/v1/posts/:id

Fetch a single scheduled post by UUID with its platform and media details.

Path parameter:
```
id - Scheduled post UUID
```

Response:
```
{ "post": { ...post fields, "scheduled_post_platforms": [...], "scheduled_post_media": [...] } }
```

Example:
```
curl https://cortex.nativz.io/api/v1/posts/3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f \
  -H "Authorization: Bearer ntvz_xxx"
```