---
name: sandtime-api
description: Connect AI agents or scripts to Sandtime.io over MCP or the per-organization REST API. Use this when the user wants to log time, manage projects, query reports, or automate Sandtime.io from Claude Code, Codex, cURL, or a standard HTTP client.
license: Proprietary
metadata:
  canonical: https://sandtime.io/SKILL.md
  product: Sandtime.io
  mcp-docs: https://sandtime.io/mcp
  rest-docs: https://sandtime.io/api
  rest-openapi: https://sandtime.io/api/openapi.json
  help-center: https://sandtime.io/help
---

# Sandtime.io API Skill

Use this skill when the task involves Sandtime.io time tracking, projects, reports, users, timesheets, or organization settings from an AI agent, terminal, script, or HTTP client.

## Preferred integration order

1. Prefer MCP for AI-agent workflows. It provides higher-level tools, safer workflows, and cleaner typed outputs.
2. Use the REST API when the environment only supports plain HTTP or cURL, or when you need direct endpoint control.
3. Use the help center for user-facing product guidance and feature behavior questions.

## Authentication

- `Authorization: Bearer <YOUR_SANDTIME_ACCESS_TOKEN>`
- MCP also requires `X-Sandtime-Organization: <organization-subdomain>` because MCP runs on `mcp.sandtime.io`.
- REST resolves the organization from the hostname, for example `https://acme.sandtime.io/api`.

Today the Bearer token is copied from the `sandtime_access_token` session cookie after signing in to Sandtime.io. This is a temporary developer-preview flow. Sandtime.io is shipping a dedicated sign-in and token flow so integrators will not need to handle cookies directly.

## Canonical docs

- MCP docs: https://sandtime.io/mcp
- REST API docs: https://sandtime.io/api
- REST OpenAPI JSON: https://sandtime.io/api/openapi.json
- SKILL.md: https://sandtime.io/SKILL.md
- Help center: https://sandtime.io/help
- Pricing: https://sandtime.io/pricing
- Security: https://sandtime.io/security
- llms.txt: https://sandtime.io/llms.txt

## MCP quick start

```json
{
  "mcpServers": {
    "sandtime": {
      "type": "http",
      "url": "https://mcp.sandtime.io/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_SANDTIME_ACCESS_TOKEN>",
        "X-Sandtime-Organization": "<YOUR_ORGANIZATION_SUBDOMAIN>"
      }
    }
  }
}
```

Use MCP when you can call tools such as `get_current_user`, `get_calendar`, `list_activities`, `create_activity`, `list_projects`, `get_organization`, `create_report`, and `get_time_summary`.

## REST API quick start with cURL

```sh
curl -X GET 'https://your-organization.sandtime.io/api/organization' \
  -H "Authorization: Bearer YOUR_SANDTIME_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

The REST API works with cURL and standard HTTP clients. The main namespaces are `/activities`, `/projects`, `/users`, `/organization`, `/reports`, `/requests`, `/timesheets`, and `/geofences`. Agents can ingest the OpenAPI schema directly from the canonical JSON endpoint when they need machine-readable REST docs.

## Workflow rules for agents

1. Resolve whether MCP is available first. If yes, use MCP unless the user explicitly asks for raw HTTP or cURL.
2. For REST, identify the organization subdomain and build the base URL as `https://{organization-subdomain}.sandtime.io/api`.
3. Before creating or updating time entries, read existing activities for the same time range so you do not create overlaps blindly.
4. Use organization, project, user, and report reads to resolve IDs before writes. Do not guess IDs.
5. After writes, read the resource again when the user needs confirmation of the final state.

## REST examples

### Create a time entry over REST

```sh
curl -X POST 'https://your-organization.sandtime.io/api/activities' \
  -H "Authorization: Bearer YOUR_SANDTIME_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "billable": true,
    "endedAt": "2026-07-03T10:30:00+02:00",
    "name": "Implement API docs page",
    "projectId": "9d58c4ce-3e6f-4d06-bf47-f70d8c4af001",
    "startedAt": "2026-07-03T09:00:00+02:00"
  }'
```

Example response excerpt:

```json
{
  "billable": true,
  "endedAt": "2026-07-03T08:30:00.000Z",
  "id": "c2dbd56f-0f09-4bf8-87ae-a1c8d7e5f302",
  "name": "Implement API docs page",
  "projectId": "9d58c4ce-3e6f-4d06-bf47-f70d8c4af001",
  "startedAt": "2026-07-03T07:00:00.000Z",
  "userId": "2f9fd8a8-9f6d-4b2b-a4f4-1f1f2a7d9b9d"
}
```

### Create a saved report over REST

```sh
curl -X POST 'https://your-organization.sandtime.io/api/reports' \
  -H "Authorization: Bearer YOUR_SANDTIME_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["project"],
    "end": "2026-07-31T23:59:59+02:00",
    "filters": [],
    "hideEmptyRows": true,
    "metrics": ["time"],
    "name": "July project summary",
    "period": "custom",
    "start": "2026-07-01T00:00:00+02:00"
  }'
```

Use the full REST reference and the OpenAPI JSON for more endpoint groups, nested project-member routes, request workflows, and timesheet actions.

## Pricing and availability

- Core Sandtime.io time tracking: free for unlimited users
- Nonprofits: custom offer available
- AI features: Sandbot and the MCP server are free for eligible organizations during early access until August 31, 2026