REST API Reference

The Temps REST API provides programmatic access to every feature available in the dashboard. All endpoints return JSON and use standard HTTP methods.

Authentication

All API requests require authentication via a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://your-temps-instance/api/projects"

Obtain a token from Settings > API Keys in the dashboard.

Deployed applications receive a per-environment token automatically as the TEMPS_API_TOKEN environment variable.

Base URL

All endpoints are relative to your Temps instance URL:

https://your-temps-instance/api/

Response format

Success responses return JSON with the resource data directly:

{
  "id": 1,
  "name": "my-project",
  "slug": "my-project",
  "created_at": "2026-01-15T12:00:00Z"
}

Error responses use RFC 7807 Problem Details:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Project 42 not found"
}

Paginated responses include items and a total count:

{
  "items": [...],
  "total": 42
}

Default pagination: 20 items per page, max 100. Use ?page=2&per_page=50 query parameters.

Projects

Trigger pipeline

curl -X POST "https://your-instance/api/projects/{project_id}/trigger-pipeline" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main", "environment_id": 1}'

Deployments

Remote deployment endpoints

Deployment jobs and logs

Container management

Environments

Update settings

curl -X PUT "https://your-instance/api/projects/{id}/environments/{id}/settings" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cpu_limit": 2000,
    "memory_limit": 1024,
    "replicas": 3,
    "exposed_port": 8080
  }'

Environment variables

Create a variable

curl -X POST "https://your-instance/api/projects/{id}/env-vars" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "API_KEY",
    "value": "secret-value",
    "environment_ids": [1, 2],
    "include_in_preview": false
  }'

Domains

External services

Analytics

The visitors page is driven by two endpoints: a faceted filter source and a paginated visitor list. Both are Postgres-only — they are implemented over the visitor and ip_geolocations tables and never touch the events hypertable, so they stay fast regardless of event volume.

Visitor facets

GET /analytics/visitor-facets returns, in a single response, the top values for exactly five visitor-row dimensions: country, region, city, channel, and referrer. Each dimension is aggregated against the current segment with that dimension's own filter removed, so a selected value never collapses its own dropdown.

{
  "country": [{ "value": "United States", "code": "US", "count": 1234 }],
  "region":   [{ "value": "California", "code": null, "count": 512 }],
  "city":     [{ "value": "San Francisco", "code": null, "count": 318 }],
  "channel":  [{ "value": "Organic Search", "code": null, "count": 980 }],
  "referrer": [{ "value": "google.com", "code": null, "count": 640 }]
}

Each value is a { value, code, count } object where count is the distinct visitor count in the current segment. The code field carries a 2-letter ISO country code only for the country dimension (so the UI can render a flag); it is null for every other dimension. A null referrer is encoded as the literal string "Direct".

Segment drill-down

Selecting a facet value sets a segment filter that is passed to GET /analytics/visitors. That endpoint accepts only the same five segment filter params — filter_country, filter_region, filter_city, filter_channel, filter_referrer — alongside limit/offset pagination, and returns a VisitorsResponse with the matching visitors plus a total_count:

curl "https://your-instance/api/analytics/visitors?project_id=1&start_date=2026-05-01T00:00:00Z&end_date=2026-05-29T00:00:00Z&filter_country=United%20States&limit=50&offset=0" \
  -H "Authorization: Bearer TOKEN"

{
  "visitors": [/* VisitorInfo */],
  "total_count": 1234
}

Monitoring

Backups

Notifications

Webhooks

Users and API keys

Using the Node SDK

Instead of making raw HTTP requests, use the official Node SDK for a typed client:

import { TempsClient } from '@temps-sdk/node-sdk';

const temps = new TempsClient({
  baseUrl: 'https://your-instance.temps.dev',
  apiKey: 'your-api-key',
});

// All endpoints are available as typed methods
const { data: projects } = await temps.projects.list();
const { data: deployments } = await temps.deployments.list({ path: { project_id: 1 } });

See the Node SDK Reference for the full API.