API Reference

Complete reference for all Futurity API endpoints.

Note

For interactive API exploration, import our OpenAPI spec into your favorite API tool.

Base URL

https://api.futurity.work/v1

Authentication

All endpoints require authentication. See Authentication.

Authorization: Bearer YOUR_TOKEN

---

User

Get Current User

Get information about the authenticated user.

GET /whoami

Response:

{
  "data": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "avatar_url": "https://...",
    "organization_id": "org_xyz789",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

---

Chats

List Chats

Get all conversations for the current user.

GET /chats

Query Parameters:

Parameter	Type	Description
limit	number	Max items (default: 20)
offset	number	Pagination offset
archived	boolean	Include archived chats

Response:

{
  "data": [
    {
      "id": "chat_123",
      "title": "Q3 Report Discussion",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:22:00Z",
      "archived": false
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Create Chat

Start a new conversation.

POST /chats

Body:

{
  "title": "New Project Discussion"
}

Response:

{
  "data": {
    "id": "chat_456",
    "title": "New Project Discussion",
    "created_at": "2024-01-16T09:00:00Z"
  }
}

Get Chat

Get a specific conversation with messages.

GET /chats/:id

Response:

{
  "data": {
    "id": "chat_123",
    "title": "Q3 Report Discussion",
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Help me analyze the Q3 report",
        "created_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "I'd be happy to help...",
        "created_at": "2024-01-15T10:30:05Z"
      }
    ]
  }
}

Send Message

Send a message in a conversation.

POST /chats/:id/messages

Body:

{
  "content": "What were the key findings?",
  "attachments": [
    {
      "file_id": "file_abc",
      "type": "vault_file"
    }
  ]
}

Response:

{
  "data": {
    "id": "msg_003",
    "role": "user",
    "content": "What were the key findings?",
    "created_at": "2024-01-15T10:35:00Z"
  }
}

Note

The assistant’s response will be generated asynchronously. Poll the chat or use webhooks to get the response.

Delete Chat

Delete a conversation.

DELETE /chats/:id

Response: 204 No Content

---

Vault

List Files

Get files in Vault.

GET /vault/files

Query Parameters:

Parameter	Type	Description
folder_id	string	Filter by folder
search	string	Search filename
type	string	Filter by file type
limit	number	Max items
offset	number	Pagination offset

Response:

{
  "data": [
    {
      "id": "file_abc",
      "name": "Q3-Report.pdf",
      "type": "application/pdf",
      "size": 245000,
      "folder_id": "folder_123",
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-10T08:00:00Z"
    }
  ]
}

Upload File

Upload a file to Vault.

POST /vault/files
Content-Type: multipart/form-data

Form Data:

Field	Type	Description
file	file	The file to upload
folder_id	string	Destination folder (optional)
name	string	Override filename (optional)

Response:

{
  "data": {
    "id": "file_xyz",
    "name": "uploaded-file.pdf",
    "type": "application/pdf",
    "size": 123456,
    "created_at": "2024-01-16T10:00:00Z"
  }
}

Get File

Get file details.

GET /vault/files/:id

Response:

{
  "data": {
    "id": "file_abc",
    "name": "Q3-Report.pdf",
    "type": "application/pdf",
    "size": 245000,
    "folder_id": "folder_123",
    "download_url": "https://...",
    "shared_with": [],
    "created_at": "2024-01-10T08:00:00Z"
  }
}

Download File

Get a download URL for a file.

GET /vault/files/:id/download

Response:

{
  "data": {
    "url": "https://signed-url...",
    "expires_at": "2024-01-16T11:00:00Z"
  }
}

Delete File

Delete a file (moves to trash).

DELETE /vault/files/:id

Response: 204 No Content

---

Workflows

List Workflows

Get all workflows.

GET /workflows

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
limit	number	Max items
offset	number	Pagination offset

Response:

{
  "data": [
    {
      "id": "wf_123",
      "name": "Daily Report",
      "status": "active",
      "trigger_type": "schedule",
      "created_at": "2024-01-01T00:00:00Z",
      "last_run": "2024-01-16T09:00:00Z"
    }
  ]
}

Create Workflow

Create a new workflow.

POST /workflows

Body:

{
  "name": "New Workflow",
  "description": "Description of what it does",
  "trigger": {
    "type": "manual"
  },
  "nodes": []
}

Response:

{
  "data": {
    "id": "wf_456",
    "name": "New Workflow",
    "status": "draft",
    "created_at": "2024-01-16T10:00:00Z"
  }
}

Get Workflow

Get workflow details including nodes.

GET /workflows/:id

Response:

{
  "data": {
    "id": "wf_123",
    "name": "Daily Report",
    "status": "active",
    "trigger": {
      "type": "schedule",
      "config": {
        "cron": "0 9 * * *"
      }
    },
    "nodes": [
      {
        "id": "node_1",
        "type": "ai_task",
        "config": {...}
      }
    ]
  }
}

Update Workflow

Update a workflow.

PUT /workflows/:id

Body:

{
  "name": "Updated Name",
  "status": "active"
}

Delete Workflow

Delete a workflow.

DELETE /workflows/:id

Response: 204 No Content

Run Workflow

Manually trigger a workflow.

POST /workflows/:id/run

Body:

{
  "inputs": {
    "customer_id": "cust_123"
  }
}

Response:

{
  "data": {
    "execution_id": "exec_789",
    "status": "running",
    "started_at": "2024-01-16T10:30:00Z"
  }
}

---

Dashboards

List Dashboards

Get all dashboards.

GET /dashboards

Response:

{
  "data": [
    {
      "id": "dash_123",
      "name": "Sales Overview",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Dashboard

Create a new dashboard.

POST /dashboards

Body:

{
  "name": "New Dashboard",
  "widgets": []
}

Get Dashboard

Get dashboard with widgets.

GET /dashboards/:id

Response:

{
  "data": {
    "id": "dash_123",
    "name": "Sales Overview",
    "widgets": [
      {
        "id": "widget_1",
        "type": "metric",
        "config": {...},
        "position": {"x": 0, "y": 0, "w": 2, "h": 1}
      }
    ]
  }
}

---

Error Codes

Code	Description
UNAUTHORIZED	Invalid or missing authentication
FORBIDDEN	Insufficient permissions
NOT_FOUND	Resource doesn’t exist
VALIDATION_ERROR	Invalid request body
RATE_LIMITED	Too many requests
INTERNAL_ERROR	Server error

Next Steps

• API Overview
• Authentication