Base URL

All API requests should be made to:
https://api.structify.ai

Authentication

The Structify API uses Bearer token authentication. Include your API key in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.structify.ai/v1/sessions

Obtaining an API Key

  1. Log into the Structify Dashboard
  2. Navigate to Settings → API Keys
  3. Click “Create New Key”
  4. Copy the key immediately (it won’t be shown again)
Keep your API keys secure. Never commit them to version control or expose them in client-side code.

Request Format

Headers

All requests should include these headers:
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Accept: application/json

Request Body

POST and PUT requests should send JSON:
{
  "name": "My Workflow",
  "description": "Process daily sales data",
  "config": {
    "cache_enabled": true,
    "timeout_seconds": 300
  }
}

Response Format

Success Response

Successful responses return HTTP 200-299 with JSON:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Workflow",
  "created_at": "2024-01-15T09:30:00Z",
  "status": "active"
}

Error Response

Errors return appropriate HTTP status codes with details:
{
  "error": {
    "type": "validation_error",
    "message": "Invalid workflow configuration",
    "details": {
      "field": "config.timeout_seconds",
      "reason": "Must be between 1 and 3600"
    }
  }
}

Status Codes

CodeDescription
200Success - Request completed
201Created - Resource created
204No Content - Success with no response body
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Error - Server error

Rate Limiting

API requests are rate limited per API key:
  • Standard: 1000 requests per minute
  • Pro: 5000 requests per minute
  • Enterprise: Custom limits
Rate limit headers are included in responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

Pagination

List endpoints support pagination via query parameters:
GET /v1/workflows?limit=20&offset=40
Paginated responses include metadata:
{
  "data": [...],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 40,
    "has_more": true
  }
}

WebSocket API

Real-time updates via WebSocket connection:
const ws = new WebSocket('wss://api.structify.ai/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_API_KEY'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Event Types

  • workflow.started - Workflow execution began
  • workflow.node.complete - Node finished executing
  • workflow.completed - Workflow finished
  • workflow.failed - Workflow encountered error

API Versioning

The API is versioned via the URL path:
  • Current: /v1/
  • Legacy: /v0/ (deprecated)
We maintain backwards compatibility within major versions. Breaking changes require a new major version.

SDK Libraries

Official SDKs handle authentication and provide type safety:

OpenAPI Specification

The complete API specification is available in OpenAPI 3.0 format: You can use this specification with tools like:
  • Postman: Import for testing
  • Swagger Codegen: Generate client libraries
  • OpenAPI Generator: Create SDKs

Next Steps