AutoAPI REST Guide

Updated October 26, 2026

Overview#

ARPIA AutoAPI REST provides RESTful HTTP endpoints for direct programmatic access to your data sources. While MCP serves AI agents, AutoAPI REST is ideal for custom applications, webhooks, and server-to-server integrations.

Key Differences: AutoAPI vs MCP#

Aspect	AutoAPI REST	MCP Protocol
Purpose	Direct application integration	AI agent communication
Interface	HTTP REST	Model Context Protocol
Use Case	Webhooks, APIs, pipelines	Claude, ChatGPT, AI tools
Response	JSON data	AI-formatted responses

Both use the same token hierarchy and underlying infrastructure.

Authentication & Tokens#

For complete token hierarchy details, see the MCP Server Guide.

Quick Reference#

Collection Token: Workspace access (32 chars)
Resource Token: Endpoint access (20 chars)
Variant Token: Security rules (10-20 chars)

URL Structure#

https://cloud.arpia.ai/api/{collection-token}/{resource-token}

Authentication Methods#

# Recommended: Authorization Header
curl -H "Authorization: Bearer YOUR_COLLECTION_TOKEN"

# Alternative: URL Parameter
curl "https://cloud.arpia.ai/api/...?token=YOUR_COLLECTION_TOKEN"

Step 1: Discover Resources#

List Available Resources#

curl -X GET "https://cloud.arpia.ai/api/YOUR_COLLECTION_TOKEN" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN"

Response:

{
  "resources": [
    {
      "name": "Customer Information",
      "resource_token": "b3cb7ee2af-2c6f4ef6b5",
      "type": "Share Data",
      "description": "Customer database access"
    }
  ]
}

Step 2: Inspect Schema#

Get Resource Structure#

curl -X GET "https://cloud.arpia.ai/api/COLLECTION_TOKEN/RESOURCE_TOKEN?_schema=true" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN"

Response:

{
  "fields": [
    {
      "name": "id",
      "type": "integer",
      "filterable": true,
      "sortable": true
    },
    {
      "name": "status",
      "type": "string",
      "known_values": ["ACTIVE", "INACTIVE"],
      "filterable": true
    }
  ]
}

Step 3: Query Data#

Basic Query#

curl -X POST "https://cloud.arpia.ai/api/COLLECTION_TOKEN/RESOURCE_TOKEN" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "results": 100,
    "page": 1
  }'

Advanced Filtering#

curl -X POST "https://cloud.arpia.ai/api/COLLECTION_TOKEN/RESOURCE_TOKEN" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "status", "type": "=", "value": "ACTIVE"},
      {"field": "created", "type": ">=", "value": "2025-01-01"}
    ],
    "orderby": [
      {"field": "created", "type": "DESC"}
    ],
    "results": 50,
    "page": 1
  }'

Filter Operators#

Operator	Description	Example
`=`	Equals	`{"field": "status", "type": "=", "value": "ACTIVE"}`
`!=`	Not equals	`{"field": "status", "type": "!=", "value": "DELETED"}`
`>`, `<`	Greater/Less than	`{"field": "amount", "type": ">", "value": 1000}`
`>=`, `<=`	Greater/Less or equal	`{"field": "date", "type": ">=", "value": "2025-01-01"}`
`LIKE`	Pattern match	`{"field": "name", "type": "LIKE", "value": "%smith%"}`
`IN`	Match list	`{"field": "category", "type": "IN", "value": "A,B,C"}`

Step 4: Aggregation#

Group and Count#

curl -X POST "https://cloud.arpia.ai/api/COLLECTION_TOKEN/RESOURCE_TOKEN" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupby": ["status", "region"],
    "results": 1000
  }'

Response:

{
  "data": [
    {"status": "ACTIVE", "region": "WEST", "count": 145},
    {"status": "ACTIVE", "region": "EAST", "count": 203}
  ]
}

Step 5: Submit Data (POST Endpoints)#

Insert Records#

curl -X POST "https://cloud.arpia.ai/api/COLLECTION_TOKEN/RESOURCE_TOKEN" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "insert",
    "data": [
      {
        "name": "New Customer",
        "email": "[email protected]",
        "status": "ACTIVE"
      }
    ]
  }'

Step 6: File Operations (S3 Compatible)#

Upload File#

curl -X POST "https://cloud.arpia.ai/api/COLLECTION_TOKEN/BUCKET_TOKEN" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN" \
  -F "[email protected]" \
  -F "metadata={\"category\":\"contracts\"}"

Download File#

curl -X GET "https://cloud.arpia.ai/api/COLLECTION_TOKEN/BUCKET_TOKEN/file-id" \
  -H "Authorization: Bearer YOUR_COLLECTION_TOKEN" \
  -o downloaded-file.pdf

Performance Optimization#

Pagination Best Practices#

// Efficient pagination
async function getAllRecords(token, resource) {
  let page = 1;
  let allData = [];

  while (true) {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        results: 500,  // Optimal batch size
        page: page
      })
    });

    const data = await response.json();
    allData = allData.concat(data.data);

    if (page >= data.pages) break;
    page++;
  }

  return allData;
}

Rate Limiting#

Standard: 100 requests/minute
Burst: 150 requests/60 seconds
Enterprise: Configurable

Implement exponential backoff:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else {
        throw error;
      }
    }
  }
}

Complete Integration Example#

class ARPIAClient {
  constructor(collectionToken) {
    this.baseURL = 'https://cloud.arpia.ai/api';
    this.token = collectionToken;
  }

  async listResources() {
    const response = await fetch(`${this.baseURL}/${this.token}`, {
      headers: {
        'Authorization': `Bearer ${this.token}`
      }
    });
    return response.json();
  }

  async queryResource(resourceToken, params) {
    const response = await fetch(
      `${this.baseURL}/${this.token}/${resourceToken}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(params)
      }
    );
    return response.json();
  }

  async getActiveCustomers(resourceToken) {
    return this.queryResource(resourceToken, {
      filters: [
        {field: 'status', type: '=', value: 'ACTIVE'}
      ],
      orderby: [
        {field: 'created', type: 'DESC'}
      ],
      results: 100,
      page: 1
    });
  }
}

// Usage
const client = new ARPIAClient('your-collection-token');
const customers = await client.getActiveCustomers('resource-token');

Monitoring & Debugging#

Check Logs#

Navigate to your collection → Logs tab to view:

Request/response payloads
Error messages
Performance metrics
Access patterns

Common HTTP Status Codes#

Code	Meaning	Action
200	Success	Process response
400	Bad Request	Check JSON syntax
401	Unauthorized	Verify token
404	Not Found	Check resource token
429	Rate Limited	Implement backoff
500	Server Error	Check logs, retry

Integration with ARPIA Layers#

AutoAPI REST connects to:

Knowledge Grid: Structured data models
Workshop: Custom transformations
Data Layer: RAW → CLEAN → GOLD → OPTIMIZED
MCP Protocol: AI agent access

Postman Collection#

Import this template for quick testing:

{
  "info": {"name": "ARPIA AutoAPI"},
  "item": [
    {
      "name": "List Resources",
      "request": {
        "method": "GET",
        "header": [{
          "key": "Authorization",
          "value": "Bearer {{collection_token}}"
        }],
        "url": "{{base_url}}/{{collection_token}}"
      }
    },
    {
      "name": "Query Data",
      "request": {
        "method": "POST",
        "header": [
          {"key": "Authorization", "value": "Bearer {{collection_token}}"},
          {"key": "Content-Type", "value": "application/json"}
        ],
        "body": {
          "mode": "raw",
          "raw": "{\"filters\": [{\"field\": \"status\", \"type\": \"=\", \"value\": \"ACTIVE\"}], \"results\": 100}"
        },
        "url": "{{base_url}}/{{collection_token}}/{{resource_token}}"
      }
    }
  ],
  "variable": [
    {"key": "base_url", "value": "https://cloud.arpia.ai/api"},
    {"key": "collection_token", "value": ""},
    {"key": "resource_token", "value": ""}
  ]
}

Best Practices#

Always use HTTPS for production
Store tokens securely (environment variables)
Implement retry logic with exponential backoff
Cache responses when data is stable
Use filters to minimize data transfer
Monitor rate limits proactively
Document your integrations for maintenance

Next Steps#

Get your Collection Token from ARPIA dashboard
Test with curl commands
Implement in your application
Monitor usage and optimize queries

MCP Server Guide - AI agent setup
API Collections Overview - Platform overview
AutoAPI Documentation - Complete reference

Updated: November 2025

AutoAPI REST Guide

Overview#

Key Differences: AutoAPI vs MCP#

Authentication & Tokens#

Quick Reference#

URL Structure#

Authentication Methods#

Step 1: Discover Resources#

List Available Resources#

Step 2: Inspect Schema#

Get Resource Structure#

Step 3: Query Data#

Basic Query#

Advanced Filtering#

Filter Operators#

Step 4: Aggregation#

Group and Count#

Step 5: Submit Data (POST Endpoints)#

Insert Records#

Step 6: File Operations (S3 Compatible)#

Upload File#

Download File#

Performance Optimization#

Pagination Best Practices#

Rate Limiting#

Complete Integration Example#

Monitoring & Debugging#

Check Logs#

Common HTTP Status Codes#

Integration with ARPIA Layers#

Postman Collection#

Best Practices#

Next Steps#

Related Documentation#