Deployxa API Reference

The Deployxa API allows you to programmatically manage your projects, deployments, and infrastructure.

Base URL

https://api.deployxa.com/v1

Authentication

All API requests require authentication using an API token.

Getting Your API Token

Go to Settings → API Keys
Click "Create API Key"
Give your key a name
Copy the token (you won't see it again)

Using Your API Token

Include your token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.deployxa.com/v1/projects

Response Format

All responses are in JSON format:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API token"
  }
}

Rate Limiting

API requests are rate limited:

Free Tier: 100 requests/hour
Pro Tier: 1000 requests/hour
Enterprise: Custom limits

Rate limit headers are included in responses:

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

Projects

List Projects

GET /projects

Query Parameters:

org (string): Filter by organization
status (string): Filter by status (active, suspended, deleted)
page (number): Page number (default: 1)
limit (number): Items per page (default: 10, max: 100)

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.deployxa.com/v1/projects?org=my-org&status=active"

Response:

{
  "success": true,
  "data": [
    {
      "id": "proj_123",
      "name": "my-app",
      "framework": "Next.js",
      "status": "active",
      "repositoryUrl": "https://github.com/user/my-app",
      "branch": "main",
      "deploymentUrl": "https://my-app.deployxa.app",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 5
  }
}

Create Project

POST /projects

Request Body:

{
  "name": "my-app",
  "repositoryUrl": "https://github.com/user/my-app",
  "branch": "main",
  "framework": "Next.js",
  "organizationId": "org_123"
}

Fields:

name (string, required): Project name
repositoryUrl (string, required): GitHub repository URL
branch (string): Branch to deploy (default: main)
framework (string): Framework type (auto-detected if not specified)
organizationId (string, required): Organization ID

Response:

{
  "success": true,
  "data": {
    "id": "proj_123",
    "name": "my-app",
    "framework": "Next.js",
    "status": "active",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Get Project

GET /projects/:id

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.deployxa.com/v1/projects/proj_123

Update Project

PATCH /projects/:id

Request Body:

{
  "name": "new-name",
  "branch": "develop",
  "framework": "React"
}

Delete Project

DELETE /projects/:id

Response:

{
  "success": true,
  "message": "Project deleted successfully"
}

Deployments

List Deployments

GET /projects/:id/deployments

Query Parameters:

status (string): Filter by status (queued, building, deploying, live, failed)
page (number): Page number
limit (number): Items per page

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.deployxa.com/v1/projects/proj_123/deployments?status=live"

Response:

{
  "success": true,
  "data": [
    {
      "id": "dep_123",
      "projectId": "proj_123",
      "status": "live",
      "branch": "main",
      "commitHash": "abc123def456",
      "commitMessage": "Update homepage",
      "author": "user@example.com",
      "buildDurationMs": 45000,
      "deployDurationMs": 15000,
      "url": "https://my-app.deployxa.app",
      "createdAt": "2024-01-15T12:00:00Z"
    }
  ]
}

Create Deployment

POST /projects/:id/deployments

Request Body:

{
  "branch": "main",
  "message": "Manual deployment"
}

Fields:

branch (string): Branch to deploy (default: project's default branch)
message (string): Deployment message

Response:

{
  "success": true,
  "data": {
    "id": "dep_123",
    "status": "queued",
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Get Deployment

GET /deployments/:id

Get Deployment Logs

GET /deployments/:id/logs

Query Parameters:

type (string): Log type (build, runtime, error)
tail (number): Number of lines to return (default: 100)

Response:

{
  "success": true,
  "data": {
    "logs": "[2024-01-15 12:00:00] Building application...\n[2024-01-15 12:00:30] Build completed",
    "type": "build"
  }
}

Rollback Deployment

POST /deployments/:id/rollback

Response:

{
  "success": true,
  "data": {
    "id": "dep_124",
    "status": "queued",
    "rollbackFrom": "dep_123"
  }
}

Promote Deployment

POST /deployments/:id/promote

Promote a preview deployment to production.

Domains

List Domains

GET /projects/:id/domains

Response:

{
  "success": true,
  "data": [
    {
      "id": "dom_123",
      "domain": "example.com",
      "status": "verified",
      "sslStatus": "active",
      "verifiedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Add Domain

POST /projects/:id/domains

Request Body:

{
  "domain": "example.com"
}

Response:

{
  "success": true,
  "data": {
    "id": "dom_123",
    "domain": "example.com",
    "status": "pending",
    "dnsRecords": [
      {
        "type": "A",
        "name": "@",
        "value": "76.76.21.21"
      }
    ]
  }
}

Verify Domain

POST /projects/:id/domains/:domain/verify

Delete Domain

DELETE /projects/:id/domains/:domain

Environment Variables

List Environment Variables

GET /projects/:id/env

Response:

{
  "success": true,
  "data": [
    {
      "key": "DATABASE_URL",
      "value": "postgresql://...",
      "encrypted": true,
      "environment": "production",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Add Environment Variable

POST /projects/:id/env

Request Body:

{
  "key": "DATABASE_URL",
  "value": "postgresql://user:pass@host:5432/db",
  "encrypted": true,
  "environment": "production"
}

Fields:

key (string, required): Variable name
value (string, required): Variable value
encrypted (boolean): Encrypt the value (default: false)
environment (string): Environment (production, preview, development)

Update Environment Variable

PATCH /projects/:id/env/:key

Delete Environment Variable

DELETE /projects/:id/env/:key

Import Environment Variables

POST /projects/:id/env/import

Request Body:

{
  "variables": [
    { "key": "API_KEY", "value": "sk_test_123" },
    { "key": "DATABASE_URL", "value": "postgresql://..." }
  ],
  "overwrite": true
}

Export Environment Variables

GET /projects/:id/env/export

Query Parameters:

format (string): Export format (env, json, yaml)
environment (string): Environment to export

Response (env format):

DATABASE_URL=postgresql://...
API_KEY=sk_test_123

Organizations

List Organizations

GET /organizations

Response:

{
  "success": true,
  "data": [
    {
      "id": "org_123",
      "name": "my-org",
      "displayName": "My Organization",
      "plan": "pro",
      "memberCount": 5,
      "projectCount": 10,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Create Organization

POST /organizations

Request Body:

{
  "name": "my-org",
  "displayName": "My Organization",
  "plan": "free"
}

Get Organization

GET /organizations/:id

Update Organization

PATCH /organizations/:id

List Organization Members

GET /organizations/:id/members

Invite Organization Member

POST /organizations/:id/members/invite

Request Body:

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

Remove Organization Member

DELETE /organizations/:id/members/:email

Monitoring

Get Metrics

GET /projects/:id/metrics

Query Parameters:

period (string): Time period (1h, 24h, 7d, 30d)
metric (string): Specific metric (requests, errors, latency, bandwidth, cpu, ram)

Response:

{
  "success": true,
  "data": {
    "period": "24h",
    "metrics": {
      "requests": {
        "total": 15000,
        "success": 14850,
        "errors": 150
      },
      "latency": {
        "avg": 45,
        "p50": 40,
        "p95": 120,
        "p99": 250
      },
      "bandwidth": {
        "total": 1073741824,
        "unit": "bytes"
      }
    }
  }
}

Get Health Status

GET /projects/:id/health

Response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "uptime": 99.99,
    "lastCheck": "2024-01-15T12:00:00Z",
    "responseTime": 45
  }
}

Get Alerts

GET /projects/:id/alerts

Query Parameters:

status (string): Alert status (active, resolved)
limit (number): Number of alerts to return

Response:

{
  "success": true,
  "data": [
    {
      "id": "alert_123",
      "type": "high_error_rate",
      "status": "active",
      "message": "Error rate exceeded 5%",
      "createdAt": "2024-01-15T12:00:00Z"
    }
  ]
}

Webhooks

Webhooks allow you to receive real-time notifications about deployment events.

Supported Events

deployment.created: Deployment started
deployment.building: Build in progress
deployment.deploying: Deployment in progress
deployment.success: Deployment successful
deployment.failed: Deployment failed
domain.verified: Domain verified
domain.ssl.issued: SSL certificate issued

Creating a Webhook

POST /projects/:id/webhooks

Request Body:

{
  "url": "https://example.com/webhook",
  "events": ["deployment.success", "deployment.failed"],
  "secret": "your-webhook-secret"
}

Webhook Payload

{
  "event": "deployment.success",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "deploymentId": "dep_123",
    "projectId": "proj_123",
    "status": "live",
    "url": "https://my-app.deployxa.app"
  }
}

Verifying Webhooks

Webhooks are signed with your secret. Verify the signature:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Error Codes

Code	Description
`UNAUTHORIZED`	Invalid or missing API token
`FORBIDDEN`	Insufficient permissions
`NOT_FOUND`	Resource not found
`VALIDATION_ERROR`	Invalid request data
`RATE_LIMIT_EXCEEDED`	Too many requests
`INTERNAL_ERROR`	Server error
`SERVICE_UNAVAILABLE`	Service temporarily unavailable

SDKs

JavaScript / TypeScript

npm install @deployxa/sdk

import { Deployxa } from '@deployxa/sdk';

const client = new Deployxa({ token: 'YOUR_TOKEN' });

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

// Create deployment
const deployment = await client.deployments.create('proj_123', {
  branch: 'main'
});

Python

pip install deployxa

from deployxa import Deployxa

client = Deployxa(token='YOUR_TOKEN')

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

# Create deployment
deployment = client.deployments.create('proj_123', branch='main')

Go

go get github.com/deployxa/deployxa-go

import "github.com/deployxa/deployxa-go"

client := deployxa.NewClient("YOUR_TOKEN")

// List projects
projects, err := client.Projects.List()

// Create deployment
deployment, err := client.Deployments.Create("proj_123", &deployxa.DeploymentOptions{
    Branch: "main",
})

Examples

Deploy on Git Push

const express = require('express');
const { Deployxa } = require('@deployxa/sdk');

const app = express();
const client = new Deployxa({ token: process.env.DEPLOYXA_TOKEN });

app.post('/webhook', async (req, res) => {
  if (req.body.ref === 'refs/heads/main') {
    await client.deployments.create('proj_123', {
      branch: 'main',
      message: 'Auto-deploy from webhook'
    });
  }
  res.sendStatus(200);
});

app.listen(3000);

Monitor Deployment Status

async function monitorDeployment(deploymentId) {
  while (true) {
    const deployment = await client.deployments.get(deploymentId);
    
    if (deployment.status === 'live') {
      console.log('Deployment successful!');
      break;
    } else if (deployment.status === 'failed') {
      console.error('Deployment failed!');
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

Bulk Operations

// Deploy all projects
const projects = await client.projects.list();

for (const project of projects) {
  await client.deployments.create(project.id, {
    branch: 'main'
  });
  console.log(`Deployed ${project.name}`);
}

Best Practices

Security

Never expose API tokens in client-side code
Use environment variables for tokens
Rotate tokens regularly
Use the minimum required permissions

Performance

Cache responses when possible
Use pagination for large datasets
Implement exponential backoff for retries
Monitor rate limits

Error Handling

Always check response status
Implement retry logic for transient errors
Log errors for debugging
Handle rate limiting gracefully

Rate Limiting

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Handling Rate Limits:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const retryAfter = error.headers['retry-after'] || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
}

Changelog

v1.2.0 (2024-01-15)

Added webhook support
Added bulk environment variable import/export
Improved error messages

v1.1.0 (2024-01-01)

Added organization management endpoints
Added monitoring metrics
Added alert management

v1.0.0 (2023-12-01)

Initial release
Project management
Deployment management
Domain management
Environment variables

Resources

Need Help? Contact support@deployxa.com or join our community Discord.

Base URL​

Authentication​

Getting Your API Token​

Using Your API Token​

Response Format​

Error Responses​

Rate Limiting​

Projects​

List Projects​

Create Project​

Get Project​

Update Project​

Delete Project​

Deployments​

List Deployments​

Create Deployment​

Get Deployment​

Get Deployment Logs​

Rollback Deployment​

Promote Deployment​

Domains​

List Domains​

Add Domain​

Verify Domain​

Delete Domain​

Environment Variables​

List Environment Variables​

Add Environment Variable​

Update Environment Variable​

Delete Environment Variable​

Import Environment Variables​

Export Environment Variables​

Organizations​

List Organizations​

Create Organization​

Get Organization​

Update Organization​

List Organization Members​

Invite Organization Member​

Remove Organization Member​

Monitoring​

Get Metrics​

Get Health Status​

Get Alerts​

Webhooks​

Supported Events​

Creating a Webhook​

Webhook Payload​

Verifying Webhooks​

Error Codes​

SDKs​

JavaScript / TypeScript​

Python​

Go​

Examples​

Deploy on Git Push​

Monitor Deployment Status​

Bulk Operations​

Best Practices​

Security​

Performance​

Error Handling​

Rate Limiting​

Changelog​

v1.2.0 (2024-01-15)​

v1.1.0 (2024-01-01)​

v1.0.0 (2023-12-01)​

Related Topics​

Resources​

Base URL

Authentication

Getting Your API Token

Using Your API Token

Response Format

Error Responses

Rate Limiting

Projects

List Projects

Create Project

Get Project

Update Project

Delete Project

Deployments

List Deployments

Create Deployment

Get Deployment

Get Deployment Logs

Rollback Deployment

Promote Deployment

Domains

List Domains

Add Domain

Verify Domain

Delete Domain

Environment Variables

List Environment Variables

Add Environment Variable

Update Environment Variable

Delete Environment Variable

Import Environment Variables

Export Environment Variables

Organizations

List Organizations

Create Organization

Get Organization

Update Organization

List Organization Members

Invite Organization Member

Remove Organization Member

Monitoring

Get Metrics

Get Health Status

Get Alerts

Webhooks

Supported Events

Creating a Webhook

Webhook Payload

Verifying Webhooks

Error Codes

SDKs

JavaScript / TypeScript

Python

Go

Examples

Deploy on Git Push

Monitor Deployment Status

Bulk Operations

Best Practices

Security

Performance

Error Handling

Rate Limiting

Changelog

v1.2.0 (2024-01-15)

v1.1.0 (2024-01-01)

v1.0.0 (2023-12-01)

Related Topics

Resources