# Madless API

> Madless is a compound intelligence platform built from your own knowledge. Capture concepts, discover connections, ask questions — a mind built from yours.

## Base URL

```
https://{space}.madless.com
```

Replace `{space}` with your space subdomain (e.g., `demo`).

## Authentication

All API requests require an API key passed as a Bearer token:

```
Authorization: Bearer mad_sk_...
```

API keys are created in Admin > API Keys. Each key has scoped permissions (e.g., `canvas.read`, `canvas.write`).

## Critical Rules

1. **Every write request (POST/PUT/PATCH/DELETE) requires an `Idempotency-Key` header** — a UUID. Without it, you get a 400 error.
2. **All request bodies use `snake_case`** field names (e.g., `attached_file_ids`, not `attachedFileIds`).
3. **All responses are wrapped in `{ "data": ... }`** — always read `response.data` to get the actual payload.
4. **Pagination uses cursor-based pagination** — list endpoints accept `?limit=20&cursor=<opaque_string>`. The response includes `next_cursor` when more pages exist.
5. **Errors follow RFC 7807** — `{ "type": "/errors#not_found", "title": "not found", "status": 404, "detail": "..." }`.

## Full OpenAPI Specification

The complete OpenAPI 3.1 spec (all endpoints, schemas, examples) is available at:

```
https://docs.madless.com/openapi.json
```

**Always fetch this spec first** to get the latest endpoint details, schemas, and examples.

---

## Workflow Recipes

These are step-by-step instructions for common multi-step tasks. Follow them exactly.

### Recipe 1: Create a Concept (basic)

A concept is the core unit of knowledge in Madless.

```
POST /api/v1/canvas
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "title": "Miles Davis",
  "links": [
    {
      "url": "https://en.wikipedia.org/wiki/Miles_Davis",
      "title": "Miles Davis — Wikipedia"
    }
  ],
  "visibility": "private"
}
```

**Accepted fields:** `title`, `label_ids`, `links`, `color`, `visibility`, `attached_file_ids`, `source_ref`, `last_interacted_at`, `revisit_by`. The schema is strict — unknown fields return 400.

Response (201):
```json
{
  "data": {
    "id": "con_abc123",
    "title": "Miles Davis",
    "visibility": "private",
    "label_ids": [],
    "links": [...],
    ...
  }
}
```

Save the `data.id` — you'll need it for pages, relations, and file attachments.

### Recipe 2: Create a Concept with a Page

Pages are rich-text documents attached to concepts. **Up to 5 pages per concept.**

**Step 1:** Create the concept (Recipe 1 above). Save the returned `id`.

**Step 2:** Create a page linked to it:

```
POST /api/v1/canvas/pages
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "concept_id": "<concept_id from step 1>",
  "title": "The Complete Guide to Miles Davis",
  "sections": [
    {
      "type": "text",
      "title": "Early Life",
      "content": "Born in Alton, Illinois in 1926..."
    },
    {
      "type": "text",
      "title": "Kind of Blue",
      "content": "Released in 1959, Kind of Blue is the best-selling jazz album of all time..."
    }
  ]
}
```

**Accepted fields:** `concept_id`, `title`, `sections`, `order_index`. The schema is strict — unknown fields return 400. Max 5 pages per concept (409 Conflict if exceeded).

### Recipe 3: Upload a File and Attach to a Concept

File upload is a **three-step process**: sign → upload → register. Then attach the file to a concept.

**Step 1:** Get your default drive ID:

```
GET /api/v1/drive/drives?type=personal
```

Response: `{ "data": [{ "id": "drv_abc", "type": "personal", ... }] }`. Save the `id`.

**Step 2:** Get a signed upload URL:

```
POST /api/v1/uploads/sign
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "filename": "miles-davis.jpg",
  "drive_id": "<drive_id from step 1>",
  "mime": "image/jpeg",
  "size": 102400
}
```

Response: `{ "data": { "url": "https://storage.googleapis.com/...", "key": "spaces/t_abc/...", "region": "uk" } }`.

Save both `url` and `key`.

**Step 3:** Upload the file directly to the signed URL:

```
PUT <url from step 2>
Content-Type: image/jpeg

<raw file bytes>
```

**Step 4:** Register the uploaded file:

```
POST /api/v1/drive/files
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "name": "miles-davis.jpg",
  "size": 102400,
  "mime": "image/jpeg",
  "object_path": "<key from step 2>",
  "drive_id": "<drive_id from step 1>"
}
```

Response: `{ "data": { "file_id": "file_xyz", ... } }`. Save `file_id`.

**Step 5a:** Attach to a NEW concept (at creation time):

```
POST /api/v1/canvas
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "title": "Miles Davis",
  "attached_file_ids": ["<file_id from step 4>"]
}
```

**Step 5b:** OR attach to an EXISTING concept:

```
PATCH /api/v1/canvas/<concept_id>
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "add_file_ids": ["<file_id from step 4>"]
}
```

Use `add_file_ids` to attach and `remove_file_ids` to detach.

### Recipe 4: Connect Two Concepts with a Relation

Relations create typed links between concepts in the knowledge graph.

```
POST /api/v1/canvas/relations
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "source_id": "<concept_id_1>",
  "target_id": "<concept_id_2>",
  "relation": "influences",
  "label": "Davis pioneered modal jazz which influenced Coltrane"
}
```

**Valid relation types:**
- `related` (default) — meaningfully connected
- `influences` — one concept influences, leads to, or builds on the other
- `contradicts` — concepts are in tension or opposition
- Any custom lowercase kebab-case string is also accepted

**Rule:** `source_id` and `target_id` must be different concepts.

### Recipe 5: Release a Concept to Circle

Circle is the collective intelligence layer — shared within the space.

```
PATCH /api/v1/canvas/<concept_id>
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "visibility": "released"
}
```

To un-release: set `"visibility": "private"`.

To browse all released concepts:

```
GET /api/v1/circle?limit=50
```

### Recipe 6: Search Across Everything

```
GET /api/v1/search?q=jazz&modules=canvas,drive&limit=10
```

Response:
```json
{
  "data": {
    "results": {
      "canvas": { "concepts": [{ "id": "...", "title": "Miles Davis", "similarity": 0.92 }] },
      "drive": { "files": [...] }
    },
    "total": 15,
    "query": "jazz"
  }
}
```

**Modules:** `canvas`, `drive`, `calendar`, `circle` (comma-separated, default: all).

**Semantic search** (AI-powered, Canvas only):

```
GET /api/v1/search?q=modal harmony in jazz&semantic=true&modules=canvas
```

### Recipe 7: Create a Complete Knowledge Entry (All-in-One)

This is the full workflow for creating a rich concept with files, page, links, and relations.

**Do this in order:**

1. Get your drive ID: `GET /api/v1/drive/drives?type=personal`
2. Upload files (if any): Sign → Upload → Register (Recipe 3, steps 2-4)
3. Create concept: `POST /api/v1/canvas` with `attached_file_ids`, `links`
4. Create page: `POST /api/v1/canvas/pages` with `concept_id`
5. Create relations: `POST /api/v1/canvas/relations` to link to other concepts
6. Optionally release to Circle: `PATCH /api/v1/canvas/<id>` with `visibility: released`

**Do NOT:**
- Skip the Idempotency-Key header on any write
- Use the `/canvas/screenshot` endpoint for file uploads — it creates a new concept, not an attachment
- Send camelCase field names — use snake_case
- Try to create more than 5 pages per concept

### Recipe 8: Update a Concept

```
PATCH /api/v1/canvas/<concept_id>
Content-Type: application/json
Idempotency-Key: <generate-a-uuid>

{
  "title": "Updated Title",
  "color": "#6366f1",
  "visibility": "released"
}
```

**Accepted fields:** `title`, `color`, `visibility`, `add_label_ids`, `remove_label_ids`, `add_file_ids`, `remove_file_ids`, `last_interacted_at`, `revisit_by`. The schema is strict — unknown fields return 400. All fields are optional — only include what you want to change.

**Atomic file operations:**
- `"add_file_ids": ["file1", "file2"]` — attach files
- `"remove_file_ids": ["file3"]` — detach files

**Atomic label operations:**
- `"add_label_ids": ["lbl_1"]` — add categories
- `"remove_label_ids": ["lbl_2"]` — remove categories

### Recipe 9: Delete and Trash

**Soft-delete (trash):**

```
DELETE /api/v1/canvas/<concept_id>
Idempotency-Key: <generate-a-uuid>
```

Returns 204. The concept moves to trash and can be restored.

**Restore from trash:**

```
POST /api/v1/canvas/<concept_id>/restore
Idempotency-Key: <generate-a-uuid>
```

---

## API Modules

- **Canvas: Concepts** — CRUD for knowledge concepts, search, trash/restore, duplicate detection
- **Canvas: AI** — Ask Madless Q&A, synthesis, discovery, tensions, quality gate, insights
- **Canvas: Pages** — Rich-text pages linked to concepts (up to 5 per concept)
- **Canvas: Labels** — Concept categorization with icons and colors
- **Canvas: Layout** — Canvas view states and node positions
- **Canvas: Timeline** — Per-concept timeline entries (manual and auto)
- **Canvas: Relations** — Typed connections between concepts
- **Canvas: Utilities** — Link preview, screenshot capture, stale context
- **Calendar: Calendars** — Calendar CRUD
- **Calendar: Events** — Event CRUD with recurrence
- **Circle: Concepts** — Released concepts, absorb/reabsorb/unabsorb
- **Circle: Graph** — Circle canvas and edges
- **Circle: Discussions** — Per-concept threaded discussions
- **Drive: Drives** — Drive CRUD, quotas, module drives
- **Drive: Files** — File upload, download, sharing, trash
- **Drive: Media** — Download/preview/thumbnail URLs
- **Bridge** — External sharing via magic links, contributions
- **Notifications** — Notification CRUD and preferences
- **Users** — Profile, photo, presence, settings
- **Webhooks** — Subscription CRUD, delivery logs, test, flush
- **Backups** — Backup listing, restore, file download
- **Settings** — Per-module user settings (canvas, calendar, circle, capture, notifications)
- **Admin: People** — User management, roles, invites
- **Admin: Infrastructure** — Domain, branding, export, sessions
- **Admin: Modules** — AI credits, canvas settings, bridge settings
- **Admin: Config** — Feature entitlements, rate limits
- **Search** — Global search across canvas, drive, calendar, circle
- **Billing** — Stripe checkout, subscription management

## MCP Server (for AI tools)

Connect Claude Code, Cursor, or VS Code to your Madless knowledge graph:

```
claude mcp add --transport http madless https://{space}.madless.com/api/mcp \
  --header "Authorization: Bearer mad_sk_..."
```

Available tools: search_concepts, get_concept, create_concept, update_concept,
delete_concept, restore_concept, create_relation, list_relations, create_page,
ask_madless, synthesize_concepts, search_all, attach_image_url

## Documentation

- Full OpenAPI 3.1 spec: https://docs.madless.com/openapi.json
- Interactive API reference: https://docs.madless.com/reference
- Product: https://madless.com