Skip to main content

Resources REST API

The Resources REST API provides HTTP endpoints for CRUD operations on resources. All requests go through the BFF (Backend-for-Frontend) proxy at /api/eai/v3.

Base URL​

/api/eai/v3/resources

Authentication​

All requests require authentication via the BFF proxy. Tokens are automatically injected server-side.

# Tokens are handled automatically in browser
fetch('/api/eai/v3/resources');

Endpoints​

List Resources​

Retrieve a list of resources with optional filtering and pagination.

GET /api/eai/v3/resources

Query Parameters​

ParameterTypeRequiredDescription
typestringYesResource type identifier
filter[field]stringNoFilter by field value
sortstringNoSort field (prefix with - for descending)
limitnumberNoMaximum results (default: 50, max: 100)
offsetnumberNoPagination offset
cursorstringNoCursor for cursor-based pagination

Example Request​

curl "/api/eai/v3/resources?type=project&filter[status]=active&sort=-createdAt&limit=20"
// In browser/Next.js
const response = await fetch('/api/eai/v3/resources?' + new URLSearchParams({
  type: 'project',
  'filter[status]': 'active',
  'filter[budget.gte]': '100000',
  sort: '-createdAt',
  limit: '20'
}));

const data = await response.json();

Response​

{
  "data": [
    {
      "id": "proj_123",
      "type": "project",
      "name": "Digital Transformation",
      "status": "active",
      "budget": 500000,
      "startDate": "2026-01-15",
      "owner": "user_456",
      "createdAt": "2026-01-10T10:00:00Z",
      "updatedAt": "2026-03-01T15:30:00Z"
    }
  ],
  "total": 47,
  "hasMore": true,
  "nextCursor": "eyJpZCI6InByb2pfMTIzIn0"
}

Get Resource​

Retrieve a single resource by ID.

GET /api/eai/v3/resources/:type/:id

Example Request​

curl "/api/eai/v3/resources/project/proj_123"
const response = await fetch('/api/eai/v3/resources/project/proj_123');
const project = await response.json();

Response​

{
  "id": "proj_123",
  "type": "project",
  "name": "Digital Transformation",
  "status": "active",
  "budget": 500000,
  "startDate": "2026-01-15",
  "owner": "user_456",
  "metadata": {
    "department": "IT",
    "priority": "high"
  },
  "createdAt": "2026-01-10T10:00:00Z",
  "updatedAt": "2026-03-01T15:30:00Z"
}

Create Resource​

Create a new resource.

POST /api/eai/v3/resources/:type

Request Body​

{
  "name": "Q2 Marketing Campaign",
  "status": "active",
  "budget": 250000,
  "startDate": "2026-04-01",
  "owner": "user_789",
  "metadata": {
    "department": "Marketing",
    "priority": "medium"
  }
}

Example Request​

curl -X POST "/api/eai/v3/resources/project" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Marketing Campaign",
    "status": "active",
    "budget": 250000
  }'
const response = await fetch('/api/eai/v3/resources/project', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Q2 Marketing Campaign',
    status: 'active',
    budget: 250000,
    startDate: '2026-04-01'
  })
});

const newProject = await response.json();

Response​

{
  "id": "proj_789",
  "type": "project",
  "name": "Q2 Marketing Campaign",
  "status": "active",
  "budget": 250000,
  "startDate": "2026-04-01",
  "owner": "user_789",
  "createdAt": "2026-03-11T14:00:00Z",
  "updatedAt": "2026-03-11T14:00:00Z"
}

Update Resource​

Update an existing resource.

PUT /api/eai/v3/resources/:type/:id
PATCH /api/eai/v3/resources/:type/:id

PUT replaces the entire resource, PATCH updates only specified fields.

Request Body​

{
  "status": "completed",
  "completedAt": "2026-03-11T14:00:00Z"
}

Example Request​

curl -X PATCH "/api/eai/v3/resources/project/proj_123" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'
const response = await fetch('/api/eai/v3/resources/project/proj_123', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    status: 'completed',
    completedAt: new Date().toISOString()
  })
});

const updated = await response.json();

Response​

{
  "id": "proj_123",
  "type": "project",
  "name": "Digital Transformation",
  "status": "completed",
  "completedAt": "2026-03-11T14:00:00Z",
  "updatedAt": "2026-03-11T14:00:00Z"
}

Delete Resource​

Delete a resource.

DELETE /api/eai/v3/resources/:type/:id

Example Request​

curl -X DELETE "/api/eai/v3/resources/project/proj_123"
await fetch('/api/eai/v3/resources/project/proj_123', {
  method: 'DELETE'
});

Response​

204 No Content

Advanced Filtering​

Comparison Operators​

Use dot notation for comparison operators:

?filter[budget.gte]=100000        # Greater than or equal
?filter[budget.lt]=1000000        # Less than
?filter[status.in]=active,pending # In array
?filter[name.contains]=marketing  # String contains

Multiple Filters​

Combine multiple filters (AND logic):

?filter[status]=active&filter[budget.gte]=100000&filter[owner]=user_123

Sorting​

Single Field​

?sort=createdAt          # Ascending
?sort=-createdAt         # Descending (prefix with -)

Multiple Fields​

?sort=-priority,createdAt  # Sort by priority desc, then createdAt asc

Pagination​

Offset-based Pagination​

?limit=50&offset=0   # Page 1
?limit=50&offset=50  # Page 2

Cursor-based Pagination​

?limit=50
# Use nextCursor from previous response
?limit=50&cursor=eyJpZCI6InByb2pfMTIzIn0

Error Responses​

400 Bad Request​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid resource data",
    "details": {
      "field": "budget",
      "issue": "must be a positive number"
    }
  }
}

401 Unauthorized​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

403 Forbidden​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this resource"
  }
}

404 Not Found​

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

429 Too Many Requests​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

Rate Limits​

  • Requests: 1000 per minute per tenant
  • Rate limit headers included in all responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1678886400

Complete Example​

Full CRUD example in JavaScript:

// List active projects
const listResponse = await fetch('/api/eai/v3/resources?' + new URLSearchParams({
  type: 'project',
  'filter[status]': 'active',
  sort: '-createdAt',
  limit: '10'
}));
const { data: projects } = await listResponse.json();

// Create new project
const createResponse = await fetch('/api/eai/v3/resources/project', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'New Initiative',
    status: 'active',
    budget: 150000
  })
});
const newProject = await createResponse.json();

// Get single project
const getResponse = await fetch(`/api/eai/v3/resources/project/${newProject.id}`);
const project = await getResponse.json();

// Update project
const updateResponse = await fetch(`/api/eai/v3/resources/project/${project.id}`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    status: 'in-progress'
  })
});
const updated = await updateResponse.json();

// Delete project
await fetch(`/api/eai/v3/resources/project/${project.id}`, {
  method: 'DELETE'
});

Next Steps​