> For the complete documentation index, see [llms.txt](https://docs.gofigr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gofigr.io/api-reference/api-reference.md).

# Overview

Complete documentation of the GoFigr REST API.

**Base URL:** `https://api.gofigr.io`\
**Supported API Versions:** `v1`, `v1.1`, `v1.2`, `v1.3`, `v1.4`

All endpoints are versioned: `/api/{version}/resource/`

## Authentication

GoFigr supports two authentication methods:

| Method           | Header                                 | Use Case                       |
| ---------------- | -------------------------------------- | ------------------------------ |
| JWT Bearer Token | `Authorization: Bearer {access_token}` | Web app, short-lived sessions  |
| API Key          | `Authorization: Token {api_key}`       | Scripts, long-lived automation |

## Quick Links

* [Authentication](/api-reference/endpoints.md#authentication) — JWT tokens, API keys, password reset
* [Core Resources](/api-reference/endpoints.md#workspaces) — Workspaces, analyses, figures, revisions
* [Assets](/api-reference/endpoints.md#assets) — Data assets and asset revisions
* [Stories](/api-reference/endpoints.md#stories) — AI-powered presentations
* [Comments](/api-reference/endpoints.md#comments) — Collaboration features
* [AI & Deep Insight](/api-reference/endpoints.md#deep-insight-ai) — AI-powered analysis
* [Search](/api-reference/endpoints.md#search) — Text and image search
* [Users & Organizations](/api-reference/endpoints.md#users) — User management, organizations

## Response Format

All responses are JSON. Successful responses return `2xx` status codes.

### Error Responses

```json
{
  "error": "string",
  "detail": "string"  // optional
}
```

| Status | Meaning                                 |
| ------ | --------------------------------------- |
| 400    | Bad Request — Invalid request data      |
| 401    | Unauthorized — Authentication required  |
| 403    | Forbidden — Insufficient permissions    |
| 404    | Not Found — Resource doesn't exist      |
| 429    | Too Many Requests — Rate limit exceeded |
| 500    | Internal Server Error                   |

## Common Patterns

### Sharing

All shareable resources support user and link sharing:

```
POST /api/{version}/{resource}/{api_id}/share/user/
GET  /api/{version}/{resource}/{api_id}/share/user/
POST /api/{version}/{resource}/{api_id}/share/link/
GET  /api/{version}/{resource}/{api_id}/share/link/
```

### Thumbnails & Size

```
GET /api/{version}/{resource}/{api_id}/size/
GET /api/{version}/{resource}/{api_id}/thumbnail/
GET /api/{version}/{resource}/{api_id}/thumbnail/{size}/
```

### Query Parameters

| Parameter | Description                                           |
| --------- | ----------------------------------------------------- |
| `shallow` | Return lightweight representation without nested data |
| `silent`  | Suppress activity log generation for write operations |