> ## Documentation Index
> Fetch the complete documentation index at: https://docs.structify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> RESTful API and WebSocket endpoints for Structify

## Base URL

All API requests should be made to:

<CodeGroup>
  ```bash Production theme={null}
  https://api.structify.ai
  ```

  ```bash Development theme={null}
  http://localhost:8080
  ```
</CodeGroup>

## Authentication

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

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.structify.ai/v1/sessions
```

### Obtaining an API Key

1. Log into the [Structify Dashboard](https://app.structify.ai)
2. Navigate to Settings → API Keys
3. Click "Create New Key"
4. Copy the key immediately (it won't be shown again)

<Warning>
  Keep your API keys secure. Never commit them to version control or expose them in client-side code.
</Warning>

## Request Format

### Headers

All requests should include these headers:

```http theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Accept: application/json
```

### Request Body

POST and PUT requests should send JSON:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "message": "Invalid workflow configuration",
    "details": {
      "field": "config.timeout_seconds",
      "reason": "Must be between 1 and 3600"
    }
  }
}
```

## Status Codes

| Code | Description                                |
| ---- | ------------------------------------------ |
| 200  | Success - Request completed                |
| 201  | Created - Resource created                 |
| 204  | No Content - Success with no response body |
| 400  | Bad Request - Invalid parameters           |
| 401  | Unauthorized - Invalid or missing API key  |
| 403  | Forbidden - Insufficient permissions       |
| 404  | Not Found - Resource doesn't exist         |
| 429  | Too Many Requests - Rate limit exceeded    |
| 500  | Internal 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:

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000
```

## Pagination

List endpoints support pagination via query parameters:

```bash theme={null}
GET /v1/workflows?limit=20&offset=40
```

Paginated responses include metadata:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 40,
    "has_more": true
  }
}
```

## WebSocket API

Real-time updates via WebSocket connection:

```javascript theme={null}
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)

<Note>
  We maintain backwards compatibility within major versions. Breaking changes require a new major version.
</Note>

## SDK Libraries

Official SDKs handle authentication and provide type safety:

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="/sdks/python/installation">
    ```bash theme={null}
    pip install structifyai
    ```
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdks/typescript/installation">
    ```bash theme={null}
    npm install @structify/prospero
    ```
  </Card>
</CardGroup>

## OpenAPI Specification

The complete API specification is available in OpenAPI 3.0 format:

* [Download OpenAPI Spec](/openapi.json)
* [View in Swagger UI](https://api.structify.ai/swagger)

You can use this specification with tools like:

* **Postman**: Import for testing
* **Swagger Codegen**: Generate client libraries
* **OpenAPI Generator**: Create SDKs

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api-reference/authentication">
    Learn about authentication methods
  </Card>

  <Card title="Endpoints" icon="webhook" href="/api-reference/endpoints/overview">
    Explore available endpoints
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python/quickstart">
    Get started with Python
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdks/typescript/quickstart">
    Build with TypeScript
  </Card>
</CardGroup>