Telcofy REST Endpoints
Quick reference to Telcofy’s externally exposed REST endpoints. All paths are relative to:
- Users API –
https://users.api.telcofy.ai - Data API –
https://data.api.telcofy.ai
See authentication.md for header requirements and token exchange details.
Users Admin API
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /users/:uid/machine-accounts/list | List machine-account labels available to the customer. | x-api-key |
| POST | /users/:uid/machine-accounts | Create or rotate a machine-account API key. | x-api-key |
| POST | /login-with-apikey | Exchange an API key for a 1-hour Google OAuth token. | x-api-key |
| GET | /admin/maps | List saved admin maps (custom polygons, grids). | x-api-key |
| POST | /admin/maps | Create a new admin map. | x-api-key |
| PUT | /admin/maps/:id | Update an existing admin map. | x-api-key |
| DELETE | /admin/maps/:id | Delete an admin map. | x-api-key |
| GET | /maps/monitored | List map IDs currently flagged for realtime monitoring. | x-api-key |
Data API
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /data-agg | Run a synchronous preview of data catalogue 1.0 (activities, activity_distributions or flow; ODM is POST only). Flow is Dev environment only. See Data Aggregation API. | x-api-key |
| POST | /data-agg | Submit an aggregation job for delivered data (activities, activity_distributions, odm, flow; full=true exports to Cloud Storage). | x-api-key |
| GET | /data-agg/status/:jobId | Check aggregation job status and progress. | x-api-key |
| GET | /data-agg/results/:jobId | Retrieve preview results or export metadata (?full=true). | x-api-key |
| GET | /data-agg/jobs | List historical aggregation jobs for the caller. | x-api-key |
| GET | /data-availability | List the delivered dates per catalogue table, with day_type and row count (optional country, dataset, start_time, end_time). Dev environment only. See Data Delivery Guide. | x-api-key |
| POST | /admin/realtime | Enable or disable realtime monitoring for a saved map. | x-api-key |
| GET | /admin/realtime/data | Realtime headcount rows for monitored maps, newest first (filters: datetime_from, datetime_to, target_id, limit, offset). See Realtime Admin API. | x-api-key |
| GET | /admin/realtime/data/country | Realtime headcount rows with a by-country breakdown (same filters). Requires the country view on your account. | x-api-key |
| GET | /realtime/baseline | Night-time baseline (median of 02:00-04:59 samples) per monitored map. | x-api-key |
Response Formats
- All responses are JSON encoded and include an
errorfield on failures. - Timestamp fields follow ISO 8601 (
YYYY-MM-DDTHH:mm:ss.sssZ) unless noted. - Long-running jobs surface progress via
/data-agg/status/:jobIdand deliver export URLs via/data-agg/results/:jobId?full=true.
Refer to quickstart.md for example requests and to the individual service
readmes for in-depth payload schemas.