> ## Documentation Index
> Fetch the complete documentation index at: https://developer.comstruct.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for all comstruct API endpoints

## Overview

The comstruct API provides a RESTful interface for construction materials procurement. This reference documents all available endpoints with interactive "Try it" features.

## Base URL

Send all API requests to:

```
https://api.comstruct.com/v1
```

<Note>
  Calendar endpoints use the base URL `https://api.comstruct.com` without the `/v1` prefix.
</Note>

## Authentication

All endpoints require API key authentication via the `x-api-key` header:

```bash theme={null}
curl -X GET "https://api.comstruct.com/v1/projects" \
  -H "x-api-key: YOUR_API_KEY"
```

### Permissions (scopes)

API keys have specific permissions in the format `resource:action`. Each endpoint only requires the scopes relevant to it; required permissions are shown per endpoint.

**Available permissions:**

| Permission              | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `projects:read`         | Read project data                                            |
| `projects:write`        | Create and update projects                                   |
| `deliveries:read`       | Read delivery data                                           |
| `deliveries:write`      | Create and update deliveries                                 |
| `deliveries:patch`      | Patch deliveries and delivery components (customer API keys) |
| `invoices:read`         | Read invoice data                                            |
| `invoices:write`        | Create and update invoices                                   |
| `project_regions:read`  | Read project region data                                     |
| `project_regions:write` | Create and update project regions                            |
| `accounts:read`         | Read account data                                            |
| `accounts:write`        | Create and update accounts                                   |
| `payment_terms:read`    | Read payment term data                                       |
| `payment_terms:write`   | Create and update payment terms                              |
| `tax_codes:read`        | Read tax code data                                           |
| `tax_codes:write`       | Create and update tax codes                                  |
| `legal_entities:read`   | Read company code data                                       |
| `legal_entities:write`  | Create and update company codes                              |
| `users:read`            | Read user data (project user management)                     |
| `roles:read`            | Read role data (project role assignment)                     |
| `tenant_settings:read`  | Read tenant settings                                         |
| `suppliers:write`       | Create and update suppliers                                  |
| `purchase_orders:write` | Create purchase orders                                       |
| `orders:write`          | Update orders as a supplier (confirm, decline, edit)         |

<Note>
  As an administrator, you can create API keys yourself in the comstruct application: **Administration → API keys**. There you configure permission scopes and receive the key once at creation time.

  Alternatively, your Customer Success Manager can help you with setup.
</Note>

## API endpoint groups

<CardGroup cols={2}>
  <Card title="Projects" icon="folder">
    Project management and queries.

    * List projects
    * Create/update project
    * Get project by ID
    * List project components
    * Import SAP projects
  </Card>

  <Card title="Deliveries" icon="truck">
    Delivery note management.

    * List deliveries
    * Create delivery notes
    * Patch deliveries and set delivery components
    * OpenTrans/PAHM/Custom formats
  </Card>

  <Card title="Invoices" icon="file-invoice">
    Invoice processing.

    * List and retrieve invoices
    * Upload invoices
    * AI-assisted analysis
  </Card>

  <Card title="Master data" icon="database">
    Manage reference data.

    * Accounts
    * Payment terms
    * Tax codes
    * Company codes
    * Project regions
  </Card>
</CardGroup>

## Rate limits

The API enforces rate limiting to ensure fair usage and system stability. Limits are applied per IP address.

| Limit         | Value        |
| ------------- | ------------ |
| Request count | 750 requests |
| Interval      | 30 seconds   |

When the limit is exceeded, requests may be throttled or denied with HTTP `403 Forbidden`. Implement exponential backoff and retry logic in your integrations to handle rate limit responses gracefully.

<Tip>
  For high-volume integrations, contact your Customer Success Manager to discuss your requirements.
</Tip>

## HTTP status codes

| Code  | Description                                           |
| ----- | ----------------------------------------------------- |
| `200` | Success                                               |
| `201` | Created                                               |
| `400` | Bad request                                           |
| `401` | Unauthorized                                          |
| `403` | Forbidden – missing permission or rate limit exceeded |
| `404` | Not found                                             |
| `500` | Server error                                          |

## Interactive API documentation

Each endpoint page includes a **"Try it"** feature so you can test API calls directly. Enter your API key and try the endpoints.

<Card title="OpenAPI specification" icon="download" href="/api-reference/openapi.yaml">
  Download the full OpenAPI 3.0 specification.
</Card>