# REST Endpoints

Complete documentation of all HTTP REST endpoints in the GoFigr server 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:**

* JWT Bearer token: `Authorization: Bearer {access_token}`
* API Key: `Authorization: Token {api_key}`

***

## Table of Contents

1. [Authentication](#authentication)
2. [Bootstrap](#bootstrap)
3. [Workspaces](#workspaces)
4. [Organizations](#organizations)
5. [Analyses](#analyses)
6. [Figures](#figures)
7. [Figure Revisions](#figure-revisions)
8. [Assets](#assets)
9. [Asset Revisions](#asset-revisions)
10. [Stories](#stories)
11. [Comments](#comments)
12. [Reactions](#reactions)
13. [Deep Insight (AI)](#deep-insight-ai)
14. [Search](#search)
15. [Users](#users)
16. [API Keys](#api-keys)
17. [SSH Keys](#ssh-keys)
18. [Git Repository](#git-repository)
19. [Data Upload](#data-upload)

***

## Authentication

### Obtain JWT Token Pair

```
POST /api/token/
```

Authenticates user and returns access/refresh token pair.

**Request Body:**

```json
{
  "username": "string",
  "password": "string",
  "remember_me": true  // optional, extends token lifetime
}
```

**Response:** `200 OK`

```json
{
  "access": "string",
  "refresh": "string"
}
```

***

### Refresh Access Token

```
POST /api/token/refresh/
```

**Request Body:**

```json
{
  "refresh": "string"
}
```

**Response:** `200 OK`

```json
{
  "access": "string"
}
```

***

### Password Reset

```
POST /api/password_reset/
```

**Request Body:**

```json
{
  "email": "string"
}
```

***

## Bootstrap

### Get Bootstrap Data

```
GET /api/{version}/bootstrap/
```

Returns all data needed for initial frontend load in a single request.

**Response:** `200 OK`

```json
{
  "user": {...},
  "workspaces": [...],
  "settings": {...},
  "info": {
    "api_version": "string"
  }
}
```

This eliminates multiple round trips on initial page load.

***

## Workspaces

### List Workspaces

```
GET /api/{version}/workspace/
```

Lists all workspaces the user has access to.

***

### Get Workspace

```
GET /api/{version}/workspace/{api_id}/
```

***

### Create Workspace

```
POST /api/{version}/workspace/
```

**Request Body:**

```json
{
  "name": "string",
  "description": "string",
  "workspace_type": "secondary"
}
```

***

### Get Workspace Overview

```
GET /api/{version}/workspace/{api_id}/overview/
```

Returns aggregated counts for the workspace.

**Response:** `200 OK`

```json
{
  "analysis_count": 10,
  "figure_count": 45,
  "asset_count": 5,
  "story_count": 3,
  "active_this_week": 2
}
```

***

### Get Workspace Dashboard

```
GET /api/{version}/workspace/{api_id}/dashboard/
```

Returns all data needed for the home view in a single request.

**Query Parameters:**

* `activity_limit` (integer): Number of activity items (default: 10, max: 50)
* `exclude_deleted` (boolean): Exclude deleted items from activity log

**Response:** `200 OK`

```json
{
  "workspace": {...},
  "overview": {...},
  "activity_log": {
    "items": [...],
    "has_more": true,
    "total_count": 100,
    "fetched_count": 10
  },
  "stories": [...]
}
```

***

### Workspace Members

```
GET  /api/{version}/workspace/{api_id}/members/
POST /api/{version}/workspace/{api_id}/members/add/
POST /api/{version}/workspace/{api_id}/members/remove/
POST /api/{version}/workspace/{api_id}/members/change/
```

***

### Workspace Sharing

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

***

## Stories

Stories are AI-generated presentations from figure collections.

### List Stories

```
GET /api/{version}/story/
```

***

### Get Story

```
GET /api/{version}/story/{api_id}/
```

**Response:**

```json
{
  "api_id": "uuid",
  "name": "string",
  "description": "string",
  "workspace": "uuid",
  "revisions": [...],
  "slides": [...],
  "created_on": "datetime",
  "updated_on": "datetime"
}
```

***

### Create Story

```
POST /api/{version}/story/
```

**Request Body:**

```json
{
  "name": "string",
  "description": "string",
  "workspace": "uuid",
  "revisions": ["uuid", "uuid", ...]  // Figure revision IDs
}
```

***

### Update Story

```
PUT /api/{version}/story/{api_id}/
PATCH /api/{version}/story/{api_id}/
```

**Request Body:**

```json
{
  "name": "string",
  "description": "string",
  "revisions": ["uuid", ...],  // Replaces all revisions
  "slides": [  // Replaces all slides
    {
      "slide_id": "string",
      "slide_type": "title|introduction|figure|goals|data|conclusion|custom",
      "position": 0,
      "content": "string",
      "revision_id": "uuid",  // For figure slides
      "slide_data": {...}
    }
  ]
}
```

***

### Delete Story

```
DELETE /api/{version}/story/{api_id}/
```

***

## Comments

Comments support Markdown, @mentions, and threading.

### List Comments

```
GET /api/{version}/comment/?target_type={type}&target_id={uuid}
```

**Query Parameters (required):**

* `target_type`: `asset`, `asset_revision`, `figure`, or `figure_revision`
* `target_id`: API ID of the target object

**Response:** `200 OK`

```json
[
  {
    "id": "uuid",
    "user": {...},
    "content": "string",
    "parent_comment_id": "uuid|null",
    "is_edited": false,
    "created_on": "datetime",
    "updated_on": "datetime"
  }
]
```

***

### Create Comment

```
POST /api/{version}/comment/
```

**Request Body:**

```json
{
  "target_type": "figure_revision",
  "target_id": "uuid",
  "content": "Great analysis! @username what do you think?",
  "parent_comment_id": "uuid"  // Optional, for replies
}
```

Mentions using `@username` trigger email notifications.

***

### Update Comment

```
PUT /api/{version}/comment/{id}/
```

Only the comment author can edit. Sets `is_edited: true`.

**Request Body:**

```json
{
  "content": "Updated comment text"
}
```

***

### Delete Comment

```
DELETE /api/{version}/comment/{id}/
```

Only the comment author can delete.

***

### Create AI Response

```
POST /api/{version}/comment/{parent_id}/create_ai_response/
```

Creates an AI-authored reply to the specified comment. The AI generates the response asynchronously.

**Response:** `201 Created` - The empty AI comment (content populated async)

***

## Reactions

Emoji reactions on comments.

### List Reactions

```
GET /api/{version}/reaction/?comment_id={uuid}
```

***

### Create Reaction

```
POST /api/{version}/reaction/
```

**Request Body:**

```json
{
  "comment_id": "uuid",
  "emoji": "👍"
}
```

***

### Delete Reaction

```
DELETE /api/{version}/reaction/{id}/
```

***

## Deep Insight (AI)

AI-powered analysis of figures using Amazon Bedrock.

### Query Deep Insight

```
POST /api/{version}/deep_insight/
```

**Request Body:**

```json
{
  "figure_revision": "uuid",
  "prompt": "Explain this figure",
  "stream": false,
  "model": "us.amazon.nova-pro-v2:0"  // Optional
}
```

**Response (non-streaming):**

```json
{
  "response": "string"
}
```

**Response (streaming):** Server-Sent Events

***

### Compare Revisions

```
POST /api/{version}/deep_insight/compare/
```

**Request Body:**

```json
{
  "left_revision": "uuid",
  "right_revision": "uuid",
  "stream": true
}
```

***

### Extract Figure Code

```
POST /api/{version}/deep_insight/figure_code/
```

Extracts the code that generated a figure using AI.

**Request Body:**

```json
{
  "figure_revision": "uuid"
}
```

**Response:**

```json
{
  "code": "string"
}
```

***

### Get Datasets

```
POST /api/{version}/deep_insight/datasets/
```

Returns data inputs/outputs for a figure revision.

**Response:**

```json
{
  "external_data": [...],
  "ai_inputs": [...],
  "ai_outputs": [...]
}
```

***

### Text-Only Query

```
POST /api/{version}/deep_insight/text_only/
```

AI query without a figure (text-only context).

**Request Body:**

```json
{
  "text": "string",
  "prompt": "string"
}
```

***

### Check Availability

```
POST /api/{version}/deep_insight/check/
```

Checks if AI can process a figure (permissions, rate limits).

**Response:**

```json
{
  "available": true,
  "messages": []
}
```

***

### Story Generation Endpoints

```
POST /api/{version}/deep_insight/story/figure/
POST /api/{version}/deep_insight/story/overviews/
POST /api/{version}/deep_insight/story/refine/
```

Optimized endpoints for AI story generation.

***

## SSH Keys

Manage SSH keys for Git repository imports.

### List SSH Keys

```
GET /api/{version}/ssh_key/
```

**Response:**

```json
[
  {
    "api_id": "uuid",
    "name": "string",
    "fingerprint": "SHA256:...",
    "is_default": true,
    "created_on": "datetime"
  }
]
```

***

### Add SSH Key

```
POST /api/{version}/ssh_key/
```

**Request Body:**

```json
{
  "name": "My Git Key",
  "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----...",
  "is_default": false
}
```

Note: Private key is stored encrypted. Never returned in API responses.

***

### Update SSH Key

```
PATCH /api/{version}/ssh_key/{api_id}/
```

**Request Body:**

```json
{
  "name": "New Name",
  "is_default": true
}
```

***

### Delete SSH Key

```
DELETE /api/{version}/ssh_key/{api_id}/
```

***

## Git Repository

### Check Repository Access

```
POST /api/{version}/git/check/
```

Validates Git repository URL and authentication.

**Request Body:**

```json
{
  "url": "https://github.com/user/repo.git",
  "ssh_key_id": "uuid"  // Optional, for SSH URLs
}
```

***

## Data Upload

### Upload User Data

```
POST /api/{version}/user_data_upload/
```

Upload and process files (Git repos, PowerPoint, Word docs).

***

## Asset Revisions - Additional Endpoints

### Find by Hash

```
POST /api/{version}/asset_revision/find_by_hash/
```

Finds asset revisions by content hash. Used for deduplication during sync.

**Request Body:**

```json
{
  "hash_type": "blake3",
  "digest": "string",
  "analysis": "uuid"  // Optional
}
```

* `hash_type` *(required)*: Hash algorithm. Currently only `blake3` is supported.
* `digest` *(required)*: The hex-encoded content hash.
* `analysis` *(optional)*: API ID of an analysis. When provided, only revisions whose parent asset belongs to that analysis are returned. When omitted, returns **all** matching revisions workspace-wide, including both scoped and unscoped assets. Note: omitting `analysis` does **not** filter to unscoped-only assets.

**Response:** `200 OK` — JSON array of matching asset revision objects, or an empty array if none found.

**Python Client:** `AssetRevision.find_by_hash(digest, hash_type="blake3", analysis=None)` **R Client:** `find_asset_revision_by_hash(gf, digest, hash_type="blake3")`

***

### Unlink Figure

```
POST /api/{version}/asset_revision/{api_id}/unlink_figure/
```

Unlinks a figure revision from an asset revision.

**Request Body:**

```json
{
  "figure_revision": "uuid",
  "anchor": "string",  // Optional
  "delete_figure_revision": false  // Optional
}
```

***

## AI Usage

### Get AI Usage

```
GET /api/{version}/ai/usage/
```

Returns AI usage statistics and quota information.

***

## API Version History

| Version  | Key Changes                                                                          |
| -------- | ------------------------------------------------------------------------------------ |
| **v1.4** | AI-generated titles and descriptions (`ai_title`, `ai_description` fields)           |
| **v1.3** | Tasks API, Comments, Reactions, `created_on_behalf` fields, optimized workspace list |
| **v1.2** | Lazy-loaded revision data (data returned separately, not inline)                     |
| **v1.1** | Nested objects in responses (analyses/figures return full objects, not just IDs)     |
| **v1**   | Original API                                                                         |

### v1.4 (Latest)

* Added `ai_title` and `ai_description` fields to figures and revisions
* AI-generated descriptions for imported content

### v1.3

* **Tasks API:** Background task tracking (`/tasks/` endpoint)
* **Comments & Reactions:** Full collaboration features
* **Attribution:** `created_on_behalf`, `created_on_behalf_name`, `created_on_behalf_email` fields
* **Performance:** ShallowWorkspaceSerializer for list operations

### v1.2

* **Revision data:** Data objects returned via separate fetch, not inline with revision
* Improves performance for large revisions

### v1.1

* **Nested objects:** Workspace responses include full analysis objects (not just IDs)
* Analysis responses include full figure objects

### v1

* Original API with core CRUD operations

***

## Notes

1. **API Versioning:** Use `v1.4` for new integrations.
2. **Data Processing:** Revisions are processed asynchronously. Check `status` endpoint.
3. **Shallow Representations:** Use `?shallow=true` for lightweight responses.
4. **Silent Operations:** Use `?silent=true` to suppress activity logs.
5. **Base64 Encoding:** Binary data is base64-encoded.
6. **Rate Limiting:** AI endpoints are rate-limited based on plan.

***

**Last Updated:** January 2026\
**API Versions Supported:** v1, v1.1, v1.2, v1.3, v1.4


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gofigr.io/api-reference/endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.