Getting Started: Your First API Call

This guide walks you through making your first request to the Operating API. By the end, you'll have authenticated successfully and retrieved a list of projects from your organization.

Prerequisites

• An Operating account
• A terminal or API client (we'll use cURL in these examples)
• Basic familiarity with REST APIs

Step 1: Get your API key

API keys are managed per organization in Operating.

1. Log in to your Operating account at https://operating.app
2. Navigate to Settings → Integrations → API Keys
3. Click Create API Key
4. Give it a descriptive name (e.g., "Development Testing")
5. Copy the API key immediately — it won't be shown again

❗️

Each organization can have only one active API key at a time. Creating a new API key immediately invalidates any existing keys. If you have integrations using an old key, they will stop working when you create a new one.

❗️

Store your API key securely. Anyone with this key can access your organization's data. Never commit API keys to version control or share them in public channels.

Step 2: Test authentication

The Operating API uses Bearer token authentication. Every request must include your API key in the Authorization header.

Let's verify your API key works by fetching the list of companies in your organization:

Bash

curl https://api.operating.app/v1/companies \
  -H "Authorization: Bearer $OPERATING_API_KEY"

Replace $OPERATING_API_KEY with your actual API key, or export it as an environment variable:

Bash

export OPERATING_API_KEY="your_api_key_here"

Expected response:

JSON

{
  "items": [
    {
      "id": "1",
      "name": "Northwind Consulting Oy",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z"
    }
  ],
  "cursor": null
}

If you see this structure, authentication is working.

Step 3: Fetch a list of projects

Now let's retrieve something more useful: your organization's projects.

Bash

curl https://api.operating.app/v1/projects \
  -H "Authorization: Bearer $OPERATING_API_KEY"

Expected response:

JSON

{
  "items": [
    {
      "id": "7001",
      "name": "Stellar Platform Modernization",
      "clientId": "4001",
      "billingType": "time-and-materials",
      "companyId": "1",
      "projectOwnerId": "1005",
      "estimatedStartDate": "2025-03-01",
      "estimatedEndDate": "2025-09-30",
      "createdAt": "2025-02-01T10:00:00Z",
      "updatedAt": "2025-02-01T10:00:00Z"
    },
    {
      "id": "7002",
      "name": "Atlas Risk Platform",
      "clientId": "4002",
      "billingType": "fixed-price",
      "revenueRecognitionMethod": "weighted-by-hours-and-rates",
      "companyId": "2",
      "projectOwnerId": "1005",
      "estimatedStartDate": "2025-04-01",
      "estimatedEndDate": "2025-12-31",
      "createdAt": "2025-03-15T14:30:00Z",
      "updatedAt": "2025-03-15T14:30:00Z"
    }
  ],
  "cursor": "eyJpZCI6IjcwMDIifQ"
}

You'll see:

• items: Array of project objects
• cursor: Pagination token for fetching the next page (null if no more results)

Step 4: Fetch a specific project

Use the project ID from the previous response to fetch full details:

Bash

curl https://api.operating.app/v1/projects/7001 \
  -H "Authorization: Bearer $OPERATING_API_KEY"

Expected response:

JSON

{
  "id": "7001",
  "name": "Stellar Platform Modernization",
  "clientId": "4001",
  "billingType": "time-and-materials",
  "companyId": "1",
  "siteId": "10",
  "projectOwnerId": "1005",
  "estimatedStartDate": "2025-03-01",
  "estimatedEndDate": "2025-09-30",
  "statusId": "9001",
  "createdAt": "2025-02-01T10:00:00Z",
  "updatedAt": "2025-02-01T10:00:00Z"
}

Single-resource endpoints return the object directly, not wrapped in an items array.

Understanding the response structure

All list endpoints return this structure:

JSON

{
  "items": [ /* array of resources */ ],
  "cursor": "pagination_token_or_null"
}

All single-resource endpoints return the object directly.

Common errors

401 Unauthorized

JSON

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Fix: Check that your API key is correct and included in the Authorization header as Bearer YOUR_KEY.

403 Forbidden

JSON

{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions to access this resource"
}

Fix: Your API key doesn't have permission to access this resource. Check your API key's permission settings in Operating.

404 Not Found

JSON

{
  "code": "NOT_FOUND",
  "message": "Resource not found"
}

Fix: The resource ID doesn't exist, or you don't have permission to see it.

Next steps

• API conventions: Pagination, filtering, sorting, and error handling — Learn how to filter lists, paginate through large result sets, and handle errors systematically
• How to set up a project with positions, allocations, and rate cards — Create a complete project workflow
• How to sync time entries from an external system — Integrate time tracking with your existing tools

Further reading

• Authentication reference — Full details on API key management and security
• Operating API entity relations — Understand how projects, positions, allocations, and time entries relate to each other
• Endpoint reference — Browse all available endpoints at https://operating.readme.io/reference