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

2. Bootstrap

3. Workspaces

4. Organizations

5. Analyses

6. Figures

7. Figure Revisions

8. Assets

9. Asset Revisions

10. Stories

11. Comments

12. Reactions

13. Deep Insight (AI)

14. Search

15. Users

16. API Keys

17. SSH Keys

18. Git Repository

19. Data Upload

---

Authentication

Obtain JWT Token Pair

POST /api/token/

Authenticates user and returns access/refresh token pair.

Request Body:

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

Response: 200 OK

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

---

Refresh Access Token

POST /api/token/refresh/

Request Body:

{
  "refresh": "string"
}

Response: 200 OK

{
  "access": "string"
}

---

Password Reset

POST /api/password_reset/

Request Body:

{
  "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

{
  "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:

{
  "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

{
  "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

{
  "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:

{
  "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:

{
  "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:

{
  "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

[
  {
    "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:

{
  "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:

{
  "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:

{
  "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:

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

Response (non-streaming):

{
  "response": "string"
}

Response (streaming): Server-Sent Events

---

Compare Revisions

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

Request Body:

{
  "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:

{
  "figure_revision": "uuid"
}

Response:

{
  "code": "string"
}

---

Get Datasets

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

Returns data inputs/outputs for a figure revision.

Response:

{
  "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:

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

---

Check Availability

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

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

Response:

{
  "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:

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

---

Add SSH Key

POST /api/{version}/ssh_key/

Request Body:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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