> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.sibe.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Getting started with the Sibe API

You can read your whole Sibe vault from your own code: folders, files, version history, BOMs and production files, all through a REST API with a personal access token. Your first request takes under five minutes.

**Base URL:** https://api.app.sibe.io
**Interactive reference:** [https://api.app.sibe.io/swagger](https://api.app.sibe.io/swagger/index.html), then select **Public API v1** in the definition dropdown
**OpenAPI spec:** https://api.app.sibe.io/swagger/public-v1/swagger.json

## 1. Create an API token

1. In the Web Dashboard, open **Settings → Personal Access Tokens**.
2. Click **Create token** and give it a name that says what it is for, for example `erp-sync`.
3. Copy the token. It is shown **once**. If you lose it, create a new one.

Tokens look like `sibe_pat_…`. Treat them like passwords: never commit one to source control, and never put one in client-side code.

## 2. Make your first request

Pass the token in the `X-Api-Key` header. This call lists the top-level folders in your workspace.

```bash
export SIBE_TOKEN="sibe_pat_xxxxxxxxxxxxxxxxxxxx"

curl https://api.app.sibe.io/v1/top-level-folders \
  -H "X-Api-Key: $SIBE_TOKEN"
```

A successful response:

```json
{
  "topLevelFolders": [
    { "id": 1234, "name": "My Project" }
  ],
  "nextCursor": null
}
```

**Paging.** Lists return up to 10 items by default and up to 50 with `?limit=50`. When there is more, the response carries a `nextCursor` value. Pass it back as `?cursor=…` to fetch the next page. A `null` cursor means you have everything.

## 3. Key resources

| Resource | Endpoint |
| ---- |
| Root folders | `GET /v1/top-level-folders` |
| Root folder contents | `GET /v1/top-level-folders/{topLevelFolderId}/children` |
| Folder contents | `GET /v1/items/{itemId}/children` |
| Folder details | `GET /v1/items/{itemId}` |
| List files | `GET /v1/files` |
| File details | `GET /v1/files/{fileId}` |
| Find files by name | `POST /v1/files:lookup` |
| Version history | `GET /v1/files/{fileId}/versions` |
| Version metadata | `GET /v1/files/{fileId}/versions/{versionId}/metadata` |
| BOM | `GET /v1/files/{fileId}/versions/{versionId}/bom` |
| Artifacts | `GET /v1/files/{fileId}/versions/{versionId}/artifacts` |
| Download a version | `GET /v1/files/{fileId}/versions/{versionId}/download` |
| Bulk download (async) | `POST /v1/files:download`, then poll `GET /v1/downloads/{jobId}` |
| Download archive file | `GET /v1/downloads/{jobId}/file` |
| Export workspace | `GET /v1/export` |
| Resolve user IDs | `POST /v1/users:lookup` |

Every request and response schema is in the [interactive reference](https://api.app.sibe.io/swagger/index.html).

**Where each one earns its place**

* **BOM** returns the live Bill of Materials for a released assembly version, ready to push into your ERP.
* **Artifacts** lists the production files generated for a version, such as PDF, STEP, DXF and DWG, so a manufacturing system can pull them without anyone opening SOLIDWORKS® 3D CAD.
* **Bulk download** packages many files into one archive. Start the job, poll until it is done, then fetch the file.
* **Export workspace** gives you the whole workspace as one JSON file for backups or migrations.
* **Users lookup** turns the user IDs in version metadata into names, for audit reports.

## 4. Handle errors

Every error uses [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) with `Content-Type: application/problem+json`.

```json
{
  "status": 404,
  "title": "Not Found",
  "detail": "File '01234567-89ab-cdef-0123-456789abcdef' was not found.",
  "traceId": "00-7f3a1b2c3d4e5f6a-1b2c3d4e5f6a7b8c-00"
}
```

| Field | What to look at |
| ---- |
| `status` | HTTP status code |
| `title` | Short problem category |
| `detail` | Exact reason, safe to show to your users |
| `traceId` | Include this when you contact support |

**Common status codes**

| Code | Meaning |
| ---- |
| `400 Bad Request` | Request failed validation. `detail` says what to fix |
| `401 Unauthorized` | `X-Api-Key` header is missing, or the token is invalid |
| `404 Not Found` | Resource does not exist, or your token has no access to it |
| `500 Internal Server Error` | Unexpected server failure. Retry with exponential backoff, or contact support with the `traceId` |

## Common questions

**Is the API read-only?**
Yes. Public API v1 reads folders, files, versions, BOMs and artifacts, and downloads files. Check-in, check-out and releases happen in the add-in and the Web Dashboard.

**How do I revoke a token?**
Remove it under **Settings → Personal Access Tokens**. Requests with that token return `401` from then on.

**Which plan do I need for BOMs and artifacts?**
BOM Management and Automated Exports are on the [Scale plan](https://www.sibe.io/pricing), so those two endpoints return data on Scale workspaces (and on legacy Business Plus workspaces during the transition).

**Is there a rate limit?**
Yes. API access on the Scale plan is rate-limited. If you need higher limits for production work, switch on the **Increased API limits** add-on, available to Scale and Enterprise customers. Add-on pricing is on the [pricing page](https://www.sibe.io/pricing), or ask us in chat and we will enable it.

**What if I get a `500`?**
Retry with exponential backoff. If it keeps failing, send support the `traceId` from the response.

> Still stuck? Start a chat from the bottom-right of any Sibe page, or email [support@sibe.io](mailto:support@sibe.io).
>
> SOLIDWORKS is a registered trademark of Dassault Systèmes SolidWorks Corporation. Sibe is an independent product and is not affiliated with or endorsed by Dassault Systèmes.