REST API

Complete REST API reference for the NeuAIs platform.

Base URL

Production: https://api.neuais.com/v1
Staging:    https://staging-api.neuais.com/v1
Local:      http://localhost:8000/v1

Authentication

All API requests require authentication via JWT token.

Get Token

POST /auth/token

Request:

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

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use Token

Include in Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.neuais.com/v1/agents

Agents

List Agents

GET /agents

Query Parameters:

status: Filter by status (running, stopped, error)
region: Filter by region
limit: Max results (default: 100)
offset: Pagination offset

Response:

{
  "agents": [
    {
      "id": "agt_1a2b3c4d",
      "name": "my-agent",
      "status": "running",
      "replicas": 3,
      "region": "us-west-2",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:05:00Z"
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

Get Agent

GET /agents/{id}

Response:

{
  "id": "agt_1a2b3c4d",
  "name": "my-agent",
  "status": "running",
  "replicas": 3,
  "region": "us-west-2",
  "config": {
    "cpu": "1.0",
    "memory": "1Gi"
  },
  "endpoints": [
    "https://my-agent.neuais.app"
  ],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:05:00Z"
}

Create Agent

POST /agents

Request:

{
  "name": "my-agent",
  "runtime": "rust",
  "binary_url": "https://storage.neuais.com/binaries/my-agent",
  "config": {
    "cpu": "1.0",
    "memory": "1Gi",
    "replicas": 3
  },
  "environment": {
    "LOG_LEVEL": "info"
  }
}

Response:

{
  "id": "agt_1a2b3c4d",
  "name": "my-agent",
  "status": "deploying",
  "created_at": "2024-01-15T10:00:00Z"
}

Update Agent

PUT /agents/{id}

Request:

{
  "binary_url": "https://storage.neuais.com/binaries/my-agent-v2",
  "config": {
    "replicas": 5
  }
}

Delete Agent

DELETE /agents/{id}

Response:

{
  "message": "Agent deleted successfully"
}

Start Agent

POST /agents/{id}/start

Stop Agent

POST /agents/{id}/stop

Restart Agent

POST /agents/{id}/restart

Scale Agent

POST /agents/{id}/scale

Request:

{
  "replicas": 5
}

Logs

Get Logs

GET /agents/{id}/logs

Query Parameters:

tail: Number of lines (default: 100)
since: Duration (e.g., “1h”, “30m”)
level: Filter by level (debug, info, warn, error)
follow: Stream logs (boolean)

Response:

{
  "logs": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "level": "info",
      "message": "Agent started"
    }
  ]
}

Stream Logs

GET /agents/{id}/logs?follow=true

Returns Server-Sent Events (SSE) stream.

Metrics

Get Metrics

GET /agents/{id}/metrics

Query Parameters:

period: Time period (1h, 24h, 7d)
metric: Specific metric (cpu, memory, network)

Response:

{
  "metrics": {
    "cpu": [
      {"timestamp": "2024-01-15T10:00:00Z", "value": 45.2},
      {"timestamp": "2024-01-15T10:01:00Z", "value": 47.1}
    ],
    "memory": [
      {"timestamp": "2024-01-15T10:00:00Z", "value": 512},
      {"timestamp": "2024-01-15T10:01:00Z", "value": 524}
    ]
  }
}

Services

List Services

GET /services

Response:

{
  "services": [
    {
      "name": "auth",
      "status": "healthy",
      "version": "1.0.0",
      "uptime": "5d 12h 30m"
    }
  ]
}

Get Service Status

GET /services/{name}/status

Users

List Users

GET /users

Get User

GET /users/{id}

Create User

POST /users

Request:

{
  "email": "user@example.com",
  "password": "secure-password",
  "role": "developer"
}

Update User

PUT /users/{id}

Delete User

DELETE /users/{id}

Billing

Get Usage

GET /billing/usage

Query Parameters:

period: Time period (current, last_month)

Response:

{
  "period": "2024-01",
  "usage": {
    "compute_hours": 1000,
    "storage_gb": 500,
    "network_gb": 100
  },
  "cost": {
    "compute": 50.00,
    "storage": 10.00,
    "network": 5.00,
    "total": 65.00
  }
}

Get Invoices

GET /billing/invoices

Response:

{
  "invoices": [
    {
      "id": "inv_1a2b3c",
      "period": "2024-01",
      "amount": 65.00,
      "status": "paid",
      "due_date": "2024-02-01"
    }
  ]
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid agent configuration",
    "details": {
      "field": "replicas",
      "reason": "must be greater than 0"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`invalid_request`	400	Invalid request parameters
`unauthorized`	401	Missing or invalid authentication
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`conflict`	409	Resource conflict
`rate_limit_exceeded`	429	Too many requests
`internal_error`	500	Internal server error
`service_unavailable`	503	Service temporarily unavailable

Rate Limiting

API requests are rate limited:

Free tier: 100 requests/minute
Pro tier: 1000 requests/minute
Enterprise: Custom limits

Rate limit headers:

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

Pagination

List endpoints support pagination:

GET /agents?limit=50&offset=100

Response includes pagination metadata:

{
  "agents": [...],
  "total": 500,
  "limit": 50,
  "offset": 100,
  "has_more": true
}

Filtering

Use query parameters for filtering:

GET /agents?status=running&region=us-west-2

Sorting

Use sort parameter:

GET /agents?sort=created_at:desc

Field Selection

Use fields parameter:

GET /agents?fields=id,name,status

Webhooks

Create Webhook

POST /webhooks

Request:

{
  "url": "https://example.com/webhook",
  "events": ["agent.created", "agent.stopped"],
  "secret": "your-webhook-secret"
}

Webhook Events

agent.created
agent.updated
agent.deleted
agent.started
agent.stopped
agent.error

Webhook Payload

{
  "event": "agent.created",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "agent_id": "agt_1a2b3c4d",
    "name": "my-agent"
  }
}

SDK Examples

Rust

#![allow(unused)]
fn main() {
use neuais_sdk::Client;

let client = Client::new("your-token")?;
let agents = client.agents().list().await?;
}

Go

client := neuais.NewClient("your-token")
agents, err := client.Agents().List()

Python

from neuais import Client

client = Client("your-token")
agents = client.agents.list()

TypeScript

import { NeuaisClient } from '@neuais/sdk';

const client = new NeuaisClient('your-token');
const agents = await client.agents.list();

Next Steps

gRPC API - gRPC API reference
WebSocket API - Real-time WebSocket API
SDKs - Language-specific SDKs

Keyboard shortcuts

NeuAIs Documentation