API Overview

The Connix API is a RESTful API that allows you to manage projects, launch agents, and orchestrate AI workflows programmatically. All API endpoints are available at https://api.connix.io.

Base URL

https://api.connix.io

Authentication

The Connix API supports two authentication methods:

API Key Authentication

Include your API key in the X-API-Key header:

X-API-Key: your-api-key-here

OAuth2 Authentication

For browser-based applications, use OAuth2 with the authorization code flow:

Authorization: Bearer your-oauth-token

OAuth2 Endpoints:

Authorization URL: https://console.connix.io/oauth2/authorize
Token URL: https://console.connix.io/oauth2/token
Scopes: read, write

Rate Limiting

The Connix API implements rate limiting to ensure fair usage:

Rate Limit: 1000 requests per hour per API key
Burst Limit: 100 requests per minute per API key

Rate limit information is included in response headers:

X-RateLimit-Limit-Requests: 1000
X-RateLimit-Remaining-Requests: 999
X-RateLimit-Reset-Requests: 1625097600
X-RateLimit-Limit-Tokens: 10000
X-RateLimit-Remaining-Tokens: 9950
X-RateLimit-Reset-Tokens: 1625097600

When rate limits are exceeded, the API returns a 429 Too Many Requests status code.

Content Types

The API accepts and returns JSON data:

Content-Type: application/json
Accept: application/json

API Versioning

The current API version is v1. The version is included in the URL path:

https://api.connix.io/api/v1/

Common Headers

Request Headers

Content-Type: application/json
Accept: application/json
X-API-Key: your-api-key-here
User-Agent: YourApp/1.0.0
X-Request-ID: unique-request-identifier

Response Headers

Content-Type: application/json
X-Request-ID: unique-request-identifier
X-RateLimit-Remaining-Requests: 999
X-Response-Time: 150ms

Error Handling

The API uses conventional HTTP status codes and returns detailed error information:

HTTP Status Codes

Code	Description
`200`	OK - Request successful
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request data
`401`	Unauthorized - Invalid or missing authentication
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error
`503`	Service Unavailable - Service temporarily unavailable

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request data is invalid",
    "details": {
      "field": "name",
      "issue": "cannot be empty"
    },
    "request_id": "req_1234567890"
  }
}

Common Error Codes

Code	Description
`INVALID_REQUEST`	Request data validation failed
`UNAUTHORIZED`	Authentication failed
`FORBIDDEN`	Insufficient permissions
`RESOURCE_NOT_FOUND`	Requested resource doesn’t exist
`RATE_LIMIT_EXCEEDED`	Too many requests
`INTERNAL_ERROR`	Server encountered an error

API Endpoints

Core Resources

Resource	Description
Projects	Manage projects and workspaces
Agents	Launch and manage AI agents
Authentication	Handle authentication and tokens

Utility Endpoints

Endpoint	Method	Description
`/api/v1/hello`	`GET`	Health check and API test
`/api/v1/status`	`GET`	Service status and version
`/api/v1/docs`	`GET`	OpenAPI specification

Request/Response Examples

Health Check

Request:

GET /api/v1/hello?name=TestUser
X-API-Key: your-api-key-here

Response:

{
  "message": "Hello TestUser! Welcome to Connix API v1"
}

Create Project

Request:

POST /api/v1/projects
Content-Type: application/json
X-API-Key: your-api-key-here

{
  "name": "my-ai-project"
}

Response:

{
  "id": 123,
  "name": "my-ai-project",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Launch Agent

Request:

POST /api/v1/agents
Content-Type: application/json
X-API-Key: your-api-key-here

{
  "name": "data-processor",
  "project_id": 123
}

Response:

{
  "message": "Agent 'data-processor' successfully launched in project 'my-ai-project'"
}

Pagination

For endpoints that return lists, pagination is supported using query parameters:

GET /api/v1/projects?page=1&limit=20&sort=created_at&order=desc

Pagination Parameters:

page: Page number (default: 1)
limit: Items per page (default: 20, max: 100)
sort: Sort field (default: created_at)
order: Sort order (asc or desc, default: desc)

Pagination Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Filtering and Search

Many endpoints support filtering and search:

GET /api/v1/projects?search=machine-learning&status=active&created_after=2024-01-01

Common Filter Parameters:

search: Text search across name and description fields
status: Filter by resource status
created_after: Filter by creation date (ISO 8601)
created_before: Filter by creation date (ISO 8601)
updated_after: Filter by update date (ISO 8601)
updated_before: Filter by update date (ISO 8601)

Webhooks

Connix supports webhooks for real-time notifications:

POST /api/v1/webhooks
Content-Type: application/json
X-API-Key: your-api-key-here

{
  "url": "https://your-app.com/webhooks/connix",
  "events": ["agent.launched", "agent.completed", "project.created"],
  "secret": "your-webhook-secret"
}

Supported Events:

project.created
project.updated
project.deleted
agent.launched
agent.completed
agent.failed
agent.stopped

SDK Support

Official SDKs are available for multiple languages:

JavaScript/TypeScript: @connix/sdk
Python: connix-sdk
Go: github.com/connix-io/connix-go
Java: io.connix:connix-sdk
C++: connix-sdk

Each SDK handles authentication, rate limiting, and error handling automatically.

OpenAPI Specification

The complete OpenAPI 3.0 specification is available at:

https://api.connix.io/api/v1/docs

You can use this specification to generate client SDKs, test the API, or integrate with tools like Postman.

Best Practices

Authentication

Store API keys securely using environment variables
Rotate API keys regularly
Use OAuth2 for browser-based applications
Never expose API keys in client-side code

Error Handling

Always check HTTP status codes
Parse error responses for detailed information
Implement retry logic with exponential backoff
Log request IDs for debugging

Rate Limiting

Monitor rate limit headers
Implement client-side rate limiting
Use exponential backoff for retries
Consider upgrading to higher rate limits if needed

Performance

Use pagination for large datasets
Cache responses when appropriate
Use compression (gzip)
Monitor response times

Getting Help

Documentation: docs.connix.io
Community: Discord
Support: engineering@connix.io
Status Page: status.connix.io

For production issues, include your request ID and API key (partially masked) in support requests.