REST API Reference

The Temps REST API is what the dashboard and CLI use: projects, deployments, environments, domains, services, analytics, monitoring, backups and more, as JSON over standard HTTP methods. This page lists the main endpoint groups; the complete spec is served by your own instance.

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 (see Errors for status codes and common error types):

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

Paginated responses return the items under an endpoint-specific key plus a total count. The project list, for example:

{
  "projects": [...],
  "total": 42,
  "page": 1,
  "per_page": 10
}

The parameter name and defaults depend on the endpoint: the project and deployment lists take ?page=2&per_page=50 (default 10, max 100), and most other lists take page and page_size (default 20, max 100). See Pagination for the response shapes, sorting, cursor-based endpoints and iterating every page.

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": 2000000,
    "memory_limit": 1024,
    "replicas": 3,
    "exposed_port": 8080
  }'

cpu_limit is in microcores (1000000 = one core, so 2000000 is two cores) and memory_limit is in megabytes. See Resources.

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

More APIs

Some features have their own reference pages:

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://temps.example.com',
  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.