Data API

Collections, templates, extractions, records, reports, scheduled reports, and files endpoints.

Collections

Collections are user-defined structured data containers.

Method	Endpoint	Description
`GET`	`/api/v1/data/collections`	List collections
`POST`	`/api/v1/data/collections`	Create collection
`GET`	`/api/v1/data/collections/{collection_id}`	Get collection
`PUT`	`/api/v1/data/collections/{collection_id}`	Update collection
`DELETE`	`/api/v1/data/collections/{collection_id}`	Delete collection

{
  "name": "Temperature Readings",
  "schema": {
    "sensor_id": "string",
    "value": "number",
    "unit": "string",
    "timestamp": "datetime"
  }
}

Data Templates

Templates define reusable structures for collections:

Method	Endpoint	Description
`GET`	`/api/v1/data/templates`	List templates
`POST`	`/api/v1/data/templates`	Create template
`GET`	`/api/v1/data/templates/{template_id}`	Get template

Templates include validations, default values, and computed fields.

Data Extractions

Extractions process data with AI to obtain structured information:

Method	Endpoint	Description
`POST`	`/api/v1/data/extractions`	Create extraction
`GET`	`/api/v1/data/extractions/{extraction_id}`	Extraction status

{
  "source": "file_id_or_url",
  "template_id": "template_abc",
  "extraction_type": "ai",
  "model": "gemini-2.0-flash"
}

The process is asynchronous. Status progresses: pending > processing > completed / failed.

Records

Records are the data rows within a collection:

Method	Endpoint	Description
`GET`	`/api/v1/data/collections/{collection_id}/records`	List records
`POST`	`/api/v1/data/collections/{collection_id}/records`	Create record
`PUT`	`/api/v1/data/collections/{collection_id}/records/{record_id}`	Update record
`DELETE`	`/api/v1/data/collections/{collection_id}/records/{record_id}`	Delete record

Records are validated against the collection schema before storage.

Reports

Method	Endpoint	Description
`GET`	`/api/v1/data/reports`	List reports
`POST`	`/api/v1/data/reports`	Generate report
`GET`	`/api/v1/data/reports/{report_id}`	Get report

{
  "title": "Monthly Temperature Report",
  "collection_id": "col_abc123",
  "date_range": { "start": "2026-03-01", "end": "2026-03-31" },
  "format": "pdf",
  "include_charts": true
}

Scheduled Reports

Automate periodic report generation:

Method	Endpoint	Description
`POST`	`/api/v1/data/reports/scheduled`	Create scheduled report
`GET`	`/api/v1/data/reports/scheduled`	List scheduled
`DELETE`	`/api/v1/data/reports/scheduled/{schedule_id}`	Cancel schedule

{
  "report_config": { "collection_id": "col_abc123", "format": "pdf" },
  "frequency": "weekly",
  "day_of_week": "monday",
  "recipients": ["user_id_1", "user_id_2"],
  "notify_channels": ["email"]
}

Files

Method	Endpoint	Description
`POST`	`/api/v1/data/files`	Upload file
`GET`	`/api/v1/data/files/{file_id}`	Get metadata
`GET`	`/api/v1/data/files/{file_id}/url`	Download URL
`DELETE`	`/api/v1/data/files/{file_id}`	Delete file

Files are stored in GCS with at-rest encryption. Supported formats: PDF, CSV, XLSX, JSON, images (PNG, JPG). Maximum size: 50 MB per file.

Download URLs are temporary and expire in 1 hour. Request a new URL if it has expired.