Skip to main content

API Overview

Batchivo provides a RESTful API for integrating with external tools and automation.

Base URL​

Production: https://api.batchivo.example.com/api/v1
Development: http://localhost:8000/api/v1

Interactive Documentation​

When running Batchivo, access interactive API docs at:

  • Swagger UI: /docs
  • ReDoc: /redoc
  • OpenAPI Spec: /openapi.json

Authentication​

All API requests require authentication via JWT tokens.

# Get tokens
POST /api/v1/auth/login
Content-Type: application/json

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

# Response
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer"
}

Include the access token in requests:

Authorization: Bearer eyJ...

See Authentication for details.

Response Format​

All responses use JSON:

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

Error Responses​

{
  "detail": "Error message",
  "code": "ERROR_CODE"
}
StatusMeaning
400Bad Request - Invalid input
401Unauthorized - Invalid/missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
422Validation Error - Invalid data format
500Server Error - Something went wrong

Pagination​

List endpoints support pagination:

GET /api/v1/spools?skip=0&limit=20
ParameterDefaultMaxDescription
skip0-Records to skip
limit20100Records per page

Filtering​

Most list endpoints support filtering:

GET /api/v1/spools?material_type=PLA&brand=Polymaker

Sorting​

Sort by field with direction:

GET /api/v1/spools?sort_by=created_at&sort_order=desc

Rate Limiting​

API requests are rate-limited:

  • 100 requests per minute per user
  • 1000 requests per hour per user

Headers indicate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Versioning​

API version is included in the URL:

/api/v1/spools
/api/v2/spools  (future)

Endpoints​

ResourceEndpointDescription
Auth/api/v1/auth/*Authentication
Spools/api/v1/spools/*Inventory management
Products/api/v1/products/*Product catalog
Production Runs/api/v1/production-runs/*Print tracking

SDKs​

Official SDKs coming soon:

  • Python
  • TypeScript/JavaScript

Webhooks​

Webhook support planned for:

  • Inventory low stock
  • Production run completed
  • Order received