Skip to main content

API Reference

Complete API documentation for Axon OS, including REST endpoints, GraphQL schemas, and WebSocket events.

Overview​

Axon OS provides a comprehensive API suite for programmatic access to all system functionality.

API Endpoints Base URL​

https://api.axonos.com/v1

Authentication​

All API requests require authentication using one of the following methods:

  • Bearer Token: JWT token in Authorization header
  • API Key: X-API-Key header
  • OAuth 2.0: Standard OAuth flow

REST API Endpoints​

Authentication​

POST /auth/login​

Authenticate user and receive JWT token.

Request:

{
  "email": "user@example.com",
  "password": "secure_password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

POST /auth/refresh​

Refresh expired JWT token.

POST /auth/logout​

Invalidate current session.

Workflows​

GET /workflows​

List all workflows for authenticated user.

Query Parameters:

  • page (number): Page number (default: 1)
  • limit (number): Items per page (default: 10)
  • status (string): Filter by status (active, inactive, draft)
  • search (string): Search by name or description

Response:

{
  "workflows": [
    {
      "id": "wf_123",
      "name": "Data Processing Pipeline",
      "description": "ETL workflow for customer data",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T14:20:00Z",
      "node_count": 15,
      "execution_count": 1250
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 45,
    "total_pages": 5
  }
}

POST /workflows​

Create a new workflow.

Request:

{
  "name": "My New Workflow",
  "description": "Workflow description",
  "definition": {
    "nodes": [...],
    "connections": [...]
  }
}
GET /workflows/{id}
Get specific workflow by ID.

PUT /workflows/{id}
Update existing workflow.

DELETE /workflows/{id}
Delete workflow.

POST /workflows/{id}/execute
Execute workflow manually.

GET /workflows/{id}/executions
Get execution history for workflow.

Nodes​

GET /nodes​

List available nodes.

Query Parameters:

  • category (string): Filter by category
  • search (string): Search by name or description
  • version (string): Filter by version

Response:

{
  "nodes": [
    {
      "id": "node_http_request",
      "name": "HTTP Request",
      "description": "Make HTTP requests to external APIs",
      "category": "integration",
      "version": "1.2.0",
      "inputs": [
        {
          "name": "url",
          "type": "string",
          "required": true,
          "description": "Target URL for request"
        }
      ],
      "outputs": [
        {
          "name": "response",
          "type": "object",
          "description": "HTTP response data"
        }
      ]
    }
  ]
}
GET /nodes/{id}
Get specific node details.

POST /nodes
Register new custom node.

GET /nodes/{id}/versions
Get all versions of a node.

# Executions

GET /executions
List workflow executions.

GET /executions/\{id\}
Get specific execution details.

POST /executions/\{id\}/stop
Stop running execution.

GET /executions/\{id\}/logs
Get execution logs.

GraphQL API​

Endpoint​

https://api.axonos.com/v1/graphql

Schema Overview​

Queries​

type Query {
  workflows(filter: WorkflowFilter): [Workflow!]!
  workflow(id: ID!): Workflow
  nodes(filter: NodeFilter): [Node!]!
  node(id: ID!): Node
  executions(filter: ExecutionFilter): [Execution!]!
  execution(id: ID!): Execution
}

Mutations​

type Mutation {
  createWorkflow(input: CreateWorkflowInput!): Workflow!
  updateWorkflow(id: ID!, input: UpdateWorkflowInput!): Workflow!
  deleteWorkflow(id: ID!): Boolean!
  executeWorkflow(id: ID!, input: ExecuteWorkflowInput): Execution!
}

Subscriptions​

type Subscription {
  workflowExecution(workflowId: ID!): ExecutionUpdate!
  systemHealth: HealthUpdate!
}

Example Queries​

Get Workflow with Executions​

query GetWorkflow($id: ID!) {
  workflow(id: $id) {
    id
    name
    description
    status
    definition {
      nodes {
        id
        type
        position {
          x
          y
        }
        config
      }
      connections {
        from
        to
        sourcePort
        targetPort
      }
    }
    executions(limit: 10) {
      id
      status
      startTime
      endTime
      duration
    }
  }
}

WebSocket API​

Connection​

wss://api.axonos.com/v1/ws

Authentication​

Send authentication message after connection:

{
  "type": "auth",
  "token": "your_jwt_token"
}

Event Types​

Workflow Execution Updates​

{
  "type": "execution_update",
  "data": {
    "execution_id": "exec_123",
    "workflow_id": "wf_456",
    "status": "running",
    "progress": 0.65,
    "current_node": "node_789"
  }
}

System Notifications​

{
  "type": "notification",
  "data": {
    "level": "info",
    "message": "Workflow completed successfully",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

SDKs and Libraries​

JavaScript/TypeScript SDK​

npm install @axonos/sdk
import { AxonOS } from '@axonos/sdk';

const client = new AxonOS({
  apiKey: 'your_api_key',
  baseUrl: 'https://api.axonos.com/v1'
});

// List workflows
const workflows = await client.workflows.list();

// Execute workflow
const execution = await client.workflows.execute('wf_123');

Python SDK​

pip install axonos-python
from axonos import AxonOS

client = AxonOS(api_key='your_api_key')

# List workflows
workflows = client.workflows.list()

# Execute workflow
execution = client.workflows.execute('wf_123')

Rate Limiting​

Limits​

  • Standard Plan: 1000 requests/hour
  • Pro Plan: 10,000 requests/hour
  • Enterprise: Custom limits

Headers​

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Error Handling​

Standard Error Response​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}

HTTP Status Codes​

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Too Many Requests
  • 500 - Internal Server Error

API Versioning​

Current Version: v1​

  • Stable and supported
  • Breaking changes will result in new version

Upcoming: v2​

  • Enhanced GraphQL schema
  • Improved error handling
  • New WebSocket events

Need Help?​