🔌 AutoAPI REST Guide

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

📚 Related Documentation

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

Updated: November 2025