API Overview

The Futurity API allows you to programmatically access and control Futurity features from your own applications.

Base URL

All API requests are made to:

https://api.futurity.work/api/v2

Note

The API uses v2 as the current version. Some legacy v1 endpoints may still be available but new development should use v2.

Authentication

The API uses Bearer token authentication. Include your token in the Authorization header:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.futurity.work/api/v2/whoami

See Authentication for details on obtaining tokens.

Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer token
Content-Type	For POST/PUT	application/json
Accept	No	application/json (default)

Body

For requests with a body, send JSON:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Workflow"}' \
  https://api.futurity.work/api/v2/workflows

Response Format

All responses are JSON:

{
  "data": {
    "id": "wf_123",
    "name": "My Workflow",
    "status": "active"
  }
}

Success Responses

Code	Meaning
200	Success
201	Created
204	No Content (successful deletion)

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": {
      "field": "name"
    }
  }
}

Code	Meaning
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limited
500	Internal Error - Server issue

Rate Limiting

API requests are rate limited by plan:

Plan	Requests/minute
Standard	60
Professional	300
Enterprise	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1704067200

Tip

If you hit rate limits, implement exponential backoff in your retry logic.

Pagination

List endpoints support pagination:

GET /api/v2/workflows?limit=20&offset=0

Parameter	Default	Max	Description
limit	20	100	Items per page
offset	0	-	Starting position

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Filtering & Sorting

Filtering

Use query parameters to filter:

GET /api/v2/workflows?status=active&created_after=2024-01-01

Sorting

Sort results with sort parameter:

GET /api/v2/workflows?sort=-created_at

• Ascending: sort=field
• Descending: sort=-field

Available Endpoints

Core Resources

Endpoint	Description
GET /api/v2/whoami	Current user info
GET /api/v2/organizations/:id/users	List organization users
GET /api/v2/organizations/:id/users/search	Search users

Corint

Endpoint	Description
GET /api/v2/corint/history/:chat_id	Get chat history
GET /api/v2/corint/agents	List available agents
GET /api/v2/corint/tools	List available tools
POST /api/v2/corint/agents	Create custom agent
GET /api/v2/corint/analytics/token-usage-aggregates	Token usage analytics
GET /api/v2/corint/analytics/message-counts	Message count analytics
GET /api/v2/corint/analytics/tool-usage	Tool usage statistics
GET /api/v2/corint/artifact/:id	Get artifact
POST /api/v2/corint/artifact	Create artifact
GET /api/v2/integrations	List user integrations

Vault (Object Storage)

Endpoint	Description
GET /api/v2/object-storage/directories	List directory contents
POST /api/v2/object-storage/directories	Create directory
POST /api/v2/object-storage/directories/:id/rename	Rename directory
POST /api/v2/object-storage/directories/:id/move	Move directory
DELETE /api/v2/object-storage/directories/:id	Delete directory
POST /api/v2/object-storage/create	Upload file
GET /api/v2/object-storage/objects/:id	Get file details
POST /api/v2/object-storage/rename/:id	Rename file
POST /api/v2/object-storage/objects/:id/move	Move file
DELETE /api/v2/object-storage/objects/:id	Delete file
GET /api/v2/object-storage/trash	List trash items
POST /api/v2/object-storage/arbitrary/restore	Restore from trash
POST /api/v2/object-storage/arbitrary/delete	Delete from trash
DELETE /api/v2/object-storage/trash/empty	Empty trash

Workflows

Endpoint	Description
GET /api/v2/workflows	List workflows
POST /api/v2/workflows	Create workflow
GET /api/v2/workflows/:id	Get workflow
PATCH /api/v2/workflows/:id	Update workflow
GET /api/v2/workflows/:id/runs	Get workflow runs
GET /api/v2/workflows/:id/runs/:run_id	Get specific run
GET /api/v2/workflows/node-options	Get available node options

Dashboards

Endpoint	Description
GET /api/v2/dashboards	List dashboards
POST /api/v2/dashboards	Create dashboard
GET /api/v2/dashboards/:id	Get dashboard
PATCH /api/v2/dashboards/:id	Update dashboard
POST /api/v2/dashboards/:id/widgets	Add widget
DELETE /api/v2/dashboards/:id/widgets/:widget_id	Remove widget

Organizations & Users

Endpoint	Description
POST /api/v2/organizations/:id/users	Add user to organization
PUT /api/v2/organizations/:id/users/roles	Update user roles
GET /api/v2/departments/organization/:id	Get organization departments
GET /api/v2/organizations/:id/users/tree	Get user organization tree

Sharing

Endpoint	Description
GET /api/v2/sharing/:resourceType/:resourceId/shares	List shares
POST /api/v2/sharing/:resourceType/:resourceId/shares	Create share
GET /api/v2/sharing/:resourceType/:resourceId/permission	Get permission level

MCP Integrations

Endpoint	Description
GET /api/v2/mcp-integrations/services	List MCP services
GET /api/v2/mcp-integrations/connections	List user connections
GET /api/v2/mcp-integrations/connect/:serviceSlug	Connect to service
DELETE /api/v2/mcp-integrations/connections/:id	Disconnect service

SDKs

Official SDKs are coming soon:

• JavaScript/TypeScript
• Python

OpenAPI Specification

The full API specification is available as OpenAPI/Swagger:

https://api.futurity.work/swagger.json

Use this to:

• Generate client code
• Import into API tools (Postman, Insomnia)
• Build documentation

Testing

Sandbox Environment

A sandbox environment is available for testing without affecting production data.

Making Test Requests

Use curl or any HTTP client:

# Get your current user
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.futurity.work/api/v2/whoami

# List your workflows
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.futurity.work/api/v2/workflows

Versioning

The API is versioned via the URL path:

https://api.futurity.work/api/v2/...

• v2: Current stable version
• Breaking changes will result in a new version
• Old versions are supported for minimum 12 months after deprecation

Next Steps

• Authentication guide
• Full API reference