API Overview

Mars provides a comprehensive REST API for integrating your applications with external systems.

Authentication

All API requests require authentication using API keys.

Getting Your API Key

1. Navigate to Settings > API Keys
2. Click "Generate New Key"
3. Copy and store securely (won't be shown again)
4. Use in request headers

Authentication Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Base URL

https://api.mars.new/v1

Rate Limits

• Free Plan: 1,000 requests/hour
• Pro Plan: 10,000 requests/hour
• Enterprise: Custom limits

Rate limit headers included in every response:

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

Common Endpoints

Applications

List all apps

GET /apps

Get app details

GET /apps/{app_id}

Create new app

POST /apps
{
  "name": "My App",
  "description": "App description"
}

Forms

List forms

GET /apps/{app_id}/forms

Get form schema

GET /apps/{app_id}/forms/{form_id}

Submit form data

POST /apps/{app_id}/forms/{form_id}/submissions
{
  "field1": "value1",
  "field2": "value2"
}

Data Tables

Query records

GET /apps/{app_id}/tables/{table_id}/records
?filter=status:active
&sort=-created_at
&limit=50

Create record

POST /apps/{app_id}/tables/{table_id}/records
{
  "title": "New Task",
  "status": "active"
}

Update record

PUT /apps/{app_id}/tables/{table_id}/records/{record_id}
{
  "status": "completed"
}

Delete record

DELETE /apps/{app_id}/tables/{table_id}/records/{record_id}

Response Format

All responses are JSON formatted.

Success Response

{
  "success": true,
  "data": {
    "id": "123",
    "name": "Example"
  },
  "meta": {
    "timestamp": "2024-01-01T12:00:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid field value",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}

Error Codes

Webhooks

Subscribe to events in your apps:

Available Events

• form.submitted
• record.created
• record.updated
• record.deleted
• workflow.completed
• user.added

Webhook Configuration

POST /webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["form.submitted", "record.created"],
  "app_id": "app_123"
}

Webhook Payload

{
  "event": "form.submitted",
  "timestamp": "2024-01-01T12:00:00Z",
  "app_id": "app_123",
  "data": {
    "form_id": "form_456",
    "submission_id": "sub_789",
    "values": {
      "field1": "value1"
    }
  }
}

SDKs

Official SDKs available for:

• JavaScript/TypeScript
• Python
• Ruby
• PHP
• Go

JavaScript Example

import { MarsClient } from '@mars/sdk';

const client = new MarsClient({
  apiKey: 'your_api_key'
});

// Create a record
const record = await client.tables.create('tasks', {
  title: 'New Task',
  status: 'active'
});

// Query records
const records = await client.tables.query('tasks', {
  filter: { status: 'active' },
  sort: '-created_at',
  limit: 10
});

Best Practices

1. Use API Keys Securely

   • Store in environment variables
   • Never commit to source control
   • Rotate keys regularly

2. Handle Rate Limits

   • Implement exponential backoff
   • Cache responses when possible
   • Use webhooks instead of polling

3. Error Handling

   • Check status codes
   • Log errors for debugging
   • Provide user-friendly messages

4. Pagination

   • Use limit/offset parameters
   • Don't fetch more than needed
   • Process in batches

Next Steps

• Authentication
• Working with Forms
• Data Queries
• Webhooks Guide