API Reference v1.0

API Reference

Complete REST API documentation for building, deploying, and managing your infrastructure programmatically.

RESTful API

JSON Format

HTTPS Only

Base URL

https://api.example.com/v1

🔐 Authentication 👤 Users 📁 Projects 🚀 Deployments 💾 Resources 💳 Billing 🔔 Webhooks

🔐

Authentication

Secure your API requests with authentication tokens

API Key Authentication

All API requests must include your API key in the Authorization header. You can generate API keys from your dashboard.

Header Format

Authorization: Bearer YOUR_API_KEY

cURL Example

curl -X GET https://api.example.com/v1/projects \

-H "Authorization: Bearer YOUR_API_KEY" \

-H "Content-Type: application/json"

Security Best Practices

Never expose your API key in client-side code or public repositories
Rotate your API keys regularly and immediately if compromised
Use environment variables to store API keys in your applications
Implement proper error handling to avoid leaking sensitive information

👤

Users

Manage user accounts and profiles

GET /users/me

Get the authenticated user's profile information

Request Example

curl -X GET https://api.example.com/v1/users/me \

-H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "id": "usr_1234567890",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2024-01-15T10:30:00Z",
  "plan": "professional"
}

PUT /users/me

Update the authenticated user's profile

Request Body

{
  "name": "Jane Doe",
  "company": "Acme Inc"
}

Response (200 OK)

{
  "id": "usr_1234567890",
  "email": "user@example.com",
  "name": "Jane Doe",
  "company": "Acme Inc",
  "updated_at": "2024-01-20T14:25:00Z"
}

📁

Projects

Create and manage your projects

GET /projects

List all projects in your account

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)

Response (200 OK)

{
  "data": [
    {
      "id": "prj_abc123",
      "name": "my-app",
      "region": "us-east-1",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

POST /projects

Create a new project

Request Body

{
  "name": "my-new-app",
  "region": "us-west-2",
  "framework": "nodejs"
}

Response (201 Created)

{
  "id": "prj_xyz789",
  "name": "my-new-app",
  "region": "us-west-2",
  "framework": "nodejs",
  "status": "pending",
  "created_at": "2024-01-20T15:45:00Z"
}

🚀

Deployments

Deploy and manage your applications

POST /projects/:id/deployments

Create a new deployment for a project

Request Body

{
  "git_url": "https://github.com/user/repo.git",
  "branch": "main",
  "environment": {
    "NODE_ENV": "production",
    "API_KEY": "secret_key"
  }
}

Response (201 Created)

{
  "id": "dep_123abc",
  "project_id": "prj_abc123",
  "status": "building",
  "url": "https://my-app-dep123.example.com",
  "created_at": "2024-01-20T16:00:00Z"
}

⚠️

Error Handling

Understanding API error responses

Error Response Format

All errors follow a consistent JSON format:

{
  "error": {
    "code": "invalid_request",
    "message": "The request is missing required parameters",
    "details": {
      "missing_fields": ["name", "region"]
    }
  }
}

Common Error Codes

Status Code	Error Code	Description
400	`invalid_request`	The request is malformed or missing required parameters
401	`unauthorized`	Invalid or missing authentication credentials
403	`forbidden`	You don't have permission to access this resource
404	`not_found`	The requested resource does not exist
429	`rate_limit_exceeded`	Too many requests, please slow down
500	`internal_error`	An unexpected error occurred on our servers

⏱️

Rate Limiting

API usage limits and best practices

🆓

Free Tier

1,000

requests per hour

⭐

Pro Tier

10,000

requests per hour

🏢

Enterprise

Custom

unlimited requests

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 995

X-RateLimit-Reset: 1640000000

💻

SDK & Code Examples

Use our official SDKs or make direct HTTP requests

📦 JavaScript / Node.js

// Install: npm install @orbitra/sdk

const Orbitra = require('@orbitra/sdk');

const client = new Orbitra({

apiKey: 'your_api_key'

});

// Create a project

const project = await client.projects.create({

name: 'my-app',

region: 'us-east-1'

});

🐍 Python

# Install: pip install orbitra

from orbitra import Orbitra

client = Orbitra(

api_key='your_api_key'

)

# Create a project

project = client.projects.create(

name='my-app',

region='us-east-1'

)

🔧 cURL

curl -X POST https://api.example.com/v1/projects \

-H "Authorization: Bearer YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{"name":"my-app","region":"us-east-1"}'

🔔

Webhooks

Receive real-time notifications for events

Setting Up Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your account. Configure webhook endpoints in your dashboard or via API.

Available Events

• deployment.created

• deployment.succeeded

• deployment.failed

• project.created

• project.deleted

• billing.invoice.created

Webhook Payload Example

Example payload for deployment.succeeded event:

{
  "event": "deployment.succeeded",
  "timestamp": "2024-01-20T16:30:00Z",
  "data": {
    "deployment_id": "dep_123abc",
    "project_id": "prj_abc123",
    "status": "live",
    "url": "https://my-app-dep123.example.com",
    "duration_ms": 45000
  }
}

Webhook Security

All webhook requests include a signature in the X-Orbitra-Signature header. Verify this signature to ensure the request came from Orbitra.

// Verify webhook signature (Node.js)

const crypto = require('crypto');

const signature = req.headers['x-orbitra-signature'];

const payload = JSON.stringify(req.body);

const expected = crypto

.createHmac('sha256', webhookSecret)

.update(payload)

.digest('hex');

if (signature !== expected) {

throw new Error('Invalid signature');

}

Ready to Start Building?

Get your API key and start integrating Orbitra into your applications today. Need help? Our support team is here for you.

Get API Key View Documentation

Free tier includes 1,000 requests per hour • No credit card required