# Create an Application Instance
Source: https://developer.siit.io/api-reference/application-instance/create-an-application-instance

post /v1/applications/{uid}/instances
Create an application instance for a provider. Returns 409 if an instance with the same provider and external_id already exists.



# Delete an Application Instance
Source: https://developer.siit.io/api-reference/application-instance/delete-an-application-instance

delete /v1/applications/{uid}/instances/{instance_uid}
Remove an application instance



# Add a User to an Application
Source: https://developer.siit.io/api-reference/application/add-a-user-to-an-application

post /v1/applications/{uid}/users
Associate a user with an application



# Create Application
Source: https://developer.siit.io/api-reference/application/create-application

post /v1/applications
Create an Application

## Usage


# List Applications
Source: https://developer.siit.io/api-reference/application/list-applications

get /v1/applications
Fetch Applications

## Introduction

Please note archived applications are **NOT** returned.

## Usage


# List Users of an Application
Source: https://developer.siit.io/api-reference/application/list-users-of-an-application

get /v1/applications/{uid}/users
Fetch users associated with an application. Users whose App Access grant is being deprovisioned stay listed — their app_access origin carries status waiting_deprovisioning — until deprovisioning completes.



# Remove a User from an Application
Source: https://developer.siit.io/api-reference/application/remove-a-user-from-an-application

delete /v1/applications/{uid}/users/{id}
Remove a user association from an application



# Retrieve an Application
Source: https://developer.siit.io/api-reference/application/retrieve-an-application

get /v1/applications/{uid}

## Usage


# Update an Application
Source: https://developer.siit.io/api-reference/application/update-an-application

put /v1/applications/{uid}
Update an Application

## Usage


# List Approvals
Source: https://developer.siit.io/api-reference/approval/list-approvals

get /v1/approvals
Fetch Approvals across all Requests the authenticated user can access.



# List approvals
Source: https://developer.siit.io/api-reference/approval/list-approvals-for-a-request

get /v1/requests/{request_uid}/approvals
Fetch Approvals attached to a given Request.



# Retrieve an Approval
Source: https://developer.siit.io/api-reference/approval/retrieve-an-approval

get /v1/approvals/{uid}



# Archive an Article
Source: https://developer.siit.io/api-reference/article/archive-an-article

patch /v1/articles/{uid}/archive

## Introduction

Allows archiving a *draft* article.

## Usage


# Create an Article
Source: https://developer.siit.io/api-reference/article/create-an-article

post /v1/articles

## Introduction

This endpoint allows you to create a new article.
Please note that those will have a `source` marked as `external` and can only be managed through the API.

1. Articles created via this endpoint will be *automatically* `published`, and thus might be picked by the **Siit Bot**.
2. Category will be the default one when not provided.

## Usage


# List all Articles
Source: https://developer.siit.io/api-reference/article/list-all-articles

get /v1/articles
Fetch knowledge_articles

## Introduction

Notes:

1. archived Articles are **NOT** returned by default.

## Usage


# List Categories
Source: https://developer.siit.io/api-reference/article/list-categories

get /v1/articles/categories
Fetch Article categories. The response includes both top-level categories and subcategories; use `parent` to reconstruct the hierarchy, or filter with `parent_category` / `root_only`.

## Usage


# Publish an Article
Source: https://developer.siit.io/api-reference/article/publish-an-article

patch /v1/articles/{uid}/publish

## Introduction

Published articles are the only ones that can be recommended by the Siit Bot.
Please note that there is a few minutes delay between Publish and availability through the Bot.

Trying to publish an already published Article will lead to a **204** response ("No Content").

## Usage


# Retrieve an Article
Source: https://developer.siit.io/api-reference/article/retrieve-an-article

get /v1/articles/{uid}

## Introduction

Allows retrieving a *draft* or *published* Article.

## Usage


# Unarchive an Article
Source: https://developer.siit.io/api-reference/article/unarchive-an-article

patch /v1/articles/{uid}/unarchive

## Usage


# Unpublish an Article
Source: https://developer.siit.io/api-reference/article/unpublish-an-article

patch /v1/articles/{uid}/unpublish

## Introduction

Trying to unpublish a draft Article will lead to a **204** response ("No Content").

## Usage


# Update an Article
Source: https://developer.siit.io/api-reference/article/update-an-article

put /v1/articles/{uid}

## Introduction

Please note that only the ones with source `siit` or `external` can use that endpoint as the other sources are managed directly by the integrations

## Usage


# Authentication
Source: https://developer.siit.io/api-reference/authentication

Start interacting with our API

## Get your API key

Head over your [account settings](https://app.siit.io/settings/personal/authentification) to generate a Personal API key.

Please note that only the *owner* and admin roles with "Public API" permissions can generate a key and use this API.

You should then use this API key as a **Bearer Token**:

<AccordionGroup>
  <Accordion icon="rectangle-terminal" title="Testing communication">
    Once you have your key, you can run the following command in a shell to ensure that you're all set:

    ```sh theme={null}
    curl --request GET \
      --url https://api.siit.io/ping \
      --header 'Authorization: Bearer <YOUR_API_KEY>'
    ```

    If the token is valid, the result should be:

    ```json theme={null}
    {"result":"pong"}
    ```
  </Accordion>
</AccordionGroup>


# Create a Department
Source: https://developer.siit.io/api-reference/department/create-a-department

post /v1/departments



# Delete a Department
Source: https://developer.siit.io/api-reference/department/delete-a-department

delete /v1/departments/{uid}



# List Departments
Source: https://developer.siit.io/api-reference/department/list-departments

get /v1/departments
Fetch Departments



# Retrieve a Department
Source: https://developer.siit.io/api-reference/department/retrieve-a-department

get /v1/departments/{uid}



# Update a Department
Source: https://developer.siit.io/api-reference/department/update-a-department

put /v1/departments/{uid}



# Create an Equipment
Source: https://developer.siit.io/api-reference/equipment/create-an-equipment

post /v1/equipments

## Usage


# List all Equipments
Source: https://developer.siit.io/api-reference/equipment/list-all-equipments

get /v1/equipments
Fetch Equipments

## Usage


# List Categories
Source: https://developer.siit.io/api-reference/equipment/list-categories

get /v1/equipments/categories
Fetch Equipment categories

## Usage


# Retrieve an Equipment
Source: https://developer.siit.io/api-reference/equipment/retrieve-an-equipment

get /v1/equipments/{uid}

## Usage


# Update an Equipment
Source: https://developer.siit.io/api-reference/equipment/update-an-equipment

put /v1/equipments/{uid}

## Usage


# Errors
Source: https://developer.siit.io/api-reference/errors

What to expect on errors

## Introduction

**Siit** uses standard HTTP response codes to indicate the success or failure of an API request:

* `2xx` codes indicate success
* `4xx` codes indicate an error that failed given the information provided
* `5xx` codes indicate an error with Siit's servers

An `error` and a `troubleshoot` key will be present in the response payload body. The `troubleshoot` key is a readable description of the error.

More detailed HTTP response codes will be provided in endpoints documentation when applicable.

## Attributes


# Introduction
Source: https://developer.siit.io/api-reference/introduction

Welcome to the Siit API

## Caveat

Our public API is available during Trial and for customers on `Standard` & `Pro` plans.

## Base URL

The base url of the public api is [`https://api.siit.io`.](https://api.siit.io.) The API is versioned with a `/v1` suffix.

## A note about Resources

Our API uses prefixed **UID**s to identify the type of resources we're working with.
Here is a non-exhaustive list of resources you might encounter and their corresponding **UID** format:

| Resource                                                          | UID Format | Additional note                 |
| ----------------------------------------------------------------- | ---------- | ------------------------------- |
| [Request](/api-reference/request/retrieve-a-request)              | `req_x`    | (or `REQx` for legacy objects)  |
| [User](/api-reference/user/retrieve-a-user)                       | `u_x`      | (or `Ux` for legacy object)     |
| [Application](/api-reference/application/retrieve-an-application) | `s_x`      | (or `Sx` for legacy object)     |
| [Service](/api-reference/service/retrieve-a-service)              | `wa_x`     | (or `WAx` for legacy object)    |
| [Workflow](/api-reference/workflow/retrieve-a-workflow)           | `wfe_x`    | (or `WFEx` for legacy object)   |
| [Equipment](/api-reference/equipment/retrieve-an-equipment)       | `ueq_x`    | (or `UEQx` for legacy object)   |
| [Equipment Category](/api-reference/equipment/list-categories)    | `eqcat_x`  | (or `EQCATx` for legacy object) |

## Rate limiting

Please note that requests are limited to `60 requests / minutes`. Contact us if you need higher quota.

Queries made to our API will return custom headers:

| Header                | Description                                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `X-SiitApi-Limit`     | The number of HTTP requests allowed / period                                                                                       |
| `X-SiitApi-Remaining` | How many HTTP requests remain for the current period                                                                               |
| `X-SiitApi-Reset`     | This header is only returned on when you have been rate-limited and represents the timestamp at which you can start querying again |


# Create a Legal Entity
Source: https://developer.siit.io/api-reference/legal-entity/create-a-legal-entity

post /v1/legal_entities



# Delete a Legal Entity
Source: https://developer.siit.io/api-reference/legal-entity/delete-a-legal-entity

delete /v1/legal_entities/{uid}



# List Legal Entities
Source: https://developer.siit.io/api-reference/legal-entity/list-legal-entities

get /v1/legal_entities
Fetch Legal Entities



# Retrieve a Legal Entity
Source: https://developer.siit.io/api-reference/legal-entity/retrieve-a-legal-entity

get /v1/legal_entities/{uid}



# Update a Legal Entity
Source: https://developer.siit.io/api-reference/legal-entity/update-a-legal-entity

put /v1/legal_entities/{uid}



# MCP Server
Source: https://developer.siit.io/api-reference/mcp

Connect to Siit through the Model Context Protocol

Siit exposes a remote MCP server that you can connect to from any MCP-compatible client:

```
https://mcp.siit.io/mcp
```

Please note that your role needs to have **API access** to be able to authenticate via the MCP server.

For more information, consult the [dedicated help center page](https://help.siit.io/mcp-server-setup-guide).


# Create an Office Location
Source: https://developer.siit.io/api-reference/office-location/create-an-office-location

post /v1/office_locations



# Delete an Office Location
Source: https://developer.siit.io/api-reference/office-location/delete-an-office-location

delete /v1/office_locations/{uid}



# List Office Locations
Source: https://developer.siit.io/api-reference/office-location/list-office-locations

get /v1/office_locations
Fetch Office Locations



# Retrieve a Office Location
Source: https://developer.siit.io/api-reference/office-location/retrieve-an-office-location

get /v1/office_locations/{uid}



# Update an Office Location
Source: https://developer.siit.io/api-reference/office-location/update-an-office-location

put /v1/office_locations/{uid}



# Pagination
Source: https://developer.siit.io/api-reference/pagination

A few words about pagination

## Introduction

When retrieving a collection of objects with a `GET` request the result is paginated.

Pagination information is presented under `meta` object in the response body and described below.

## The meta object


# List Request Tags
Source: https://developer.siit.io/api-reference/request-tag/list-request-tags

get /v1/request_tags
Fetch Request Tags



# Retrieve a Request Tag
Source: https://developer.siit.io/api-reference/request-tag/retrieve-a-request-tag

get /v1/request_tags/{uid}



# Add followers
Source: https://developer.siit.io/api-reference/request/add-followers

post /v1/requests/{uid}/followers
Add followers to a Request. Requests outside the API key owner's request visibility, or archived requests, return a 404.

## Usage


# Archive a Request
Source: https://developer.siit.io/api-reference/request/archive-a-request

patch /v1/requests/{uid}/archive
Archive a Request. Requests outside the API key owner's request visibility return a 404.

## Usage


# Create a Request
Source: https://developer.siit.io/api-reference/request/create-a-request

post /v1/requests

## Introduction

Please note that: the `author_uid` should be the same as `requested_by_uid` **OR** reference a User with an *admin role*

## Custom forms

When submitting `custom_form_inputs[]`, you can use *arbitrary forms* and *native forms*

You can actually send a mix of *Arbitrary* and *Native* forms as long as the native form are valid.

An example payload would be:

```json theme={null}
// POST https://api.siit.io/v1/requests
{
  "title": "Request from API with forms",
  "submitted_from": "employee_portal",
  "author": "U1",
  "requested_by": "U1",
  "target_uid": "wa_xxxxx",
  "custom_form_inputs": [
    { "label": "An arbitrary field", "value": "With its arbitrary value"},
    { "uid": "custom_input_longprefix", "value": "string or uid or array or number depending on the configuration" }
  ]
}
```

**NB:** we currently don't allow uploading custom form `files` at the moment via the public API.

### Arbitrary forms

You can submit arbitrary values by sending `custom_form_inputs[]` items with the format

```json theme={null}
{ "label": "string", "value": "string" }
```

This is a good way to store extra information, but **cannot be picked by workflows**.

### Native forms

Native custom forms are always scoped by [Service object](/api-reference/service/retrieve-a-service).

If you submit *at least one native form*, then the **whole custom form validation logic will run** (e.g if you have a field that is required and missing on the payload, it will fail the creation of the request).

So the flow to use them is to:

1. retrieve the custom forms from the target you're planning on submitting `GET https://api.siit.io/v1/services/wa_xxxx` endpoint (`custom_form_input_configuration[]`)
2. add the `custom_form_inputs[]` to your request creation payload

```json theme={null}
{ "uid": "custom_input_yyyy", "value": "item | items[]" }
```

Where item should be an array if the custom form input is *multiple*.

If you have workflows configured targeting those fields, they will properly run at the request creation except in the case of a [batch import](/api-reference/request/import-past-requests).

## Usage


# Create a Request [Slack Automations]
Source: https://developer.siit.io/api-reference/request/create-a-request-directly-using-slack-informations

post /v1/requests/slack
Shorthand route for when using Slack Automations.

## Introduction

Use this route if you're plugging the request submission using [Slack Automation](https://api.slack.com/automation).

This avoid you having to fetch the user UIDs and instead directly use Slack User IDs.

A sample project interacting with this API is available [here](https://github.com/siitapp/slack-automation-sample).

## Usage


# Import past Requests
Source: https://developer.siit.io/api-reference/request/import-past-requests

post /v1/requests/batch_import

## Introduction

This endpoint allows you to import previous requests (e.g., from another ticketing system).

Please note that:

1. The imported status is derived from the payload: if `completed_at` is present the request is imported as `resolved`, otherwise it stays open.
2. You can override the `created_at` field.
3. You can import up to **200** requests at once.
4. Any row that fails to import will abort the whole process.
5. Workflows won't be triggered and Notifications won't be sent out. Even if you re-open said requests.
6. By default imported records appear as if they were created from the Admin Dashboard by the **current user** identified by the API key. You can set `submitted_from` to `employee_portal` to preserve the request's portal origin — this is the surface on which the requester can continue the conversation.
7. Specifically on this endpoint you can reference users by email instead of UID, but note that this **will** create the users
8. Imports can be made **idempotent**: provide an `import_source` (a stable namespace, e.g. the name of the source system) together with an `external_id` on each request, message, and attachment. Re-running the same import will then not create duplicate requests, messages, or attachments. Deleting an imported attachment in Siit keeps its identity, so a rerun won't resurrect it.
9. You can attach files to requests and messages: pass a publicly reachable HTTPS `url` (e.g. a pre-signed URL from your source system or bucket) together with a `filename` and an `external_id`, and Siit downloads the file during the import. Files are limited to **25 MB** each and **20** attachments per request or message; the MIME type is taken from the optional `content_type` field, the download response, or the file extension.

## Example payload

```json theme={null}
{
    "import_source": "legacy-ticketing-system",
    "items": [
        {
            "external_id": "TICKET-1234",
            "title": "Request created via Import: lorem ipsum",
            "description": "Note that workflows don't run and notifications arent fired",
            "submitted_from": "employee_portal",
            "requested_by": "u_4h72qjma",
            "assignee_admin": "bipbip@acme.com",
            "attachments": [
                {
                    "external_id": "TICKET-1234-attachment-1",
                    "url": "https://files.example.com/TICKET-1234/screenshot.png?signature=...",
                    "filename": "screenshot.png"
                }
            ],
            "messages": [
                {
                    "external_id": "TICKET-1234-message-1",
                    "body_text": "Hello this is a message",
                    "kind": "message",
                    "sent_by": "u_4h72qjma",
                    "created_at": "2026-02-27 20:55"
                },
                {
                    "external_id": "TICKET-1234-message-2",
                    "body_text": "This is a note",
                    "kind": "note",
                    "sent_by": "dimitri@siit.io",
                    "created_at": "2026-02-27 21:00"
                },
                {
                    "external_id": "TICKET-1234-message-3",
                    "body_text": "I can also create a user via this call",
                    "kind": "message",
                    "sent_by": "createme@siit.io",
                    "created_at": "2026-02-27 22:00",
                    "attachments": [
                        {
                            "external_id": "TICKET-1234-message-3-attachment-1",
                            "url": "https://files.example.com/TICKET-1234/logs.txt?signature=...",
                            "filename": "logs.txt"
                        }
                    ]
                }
            ],
            "completed_at": "2026-02-27 23:42",
            "created_at": "2026-02-27 20:50",
            "custom_form_inputs": [
                {
                    "label": "This is an arbitrary label",
                    "value": "This is the value"
                },
                {
                    "label": "Old System Request ID",
                    "value": 42
                }
            ]
        }
    ]
}
```

## Usage


# List all messages
Source: https://developer.siit.io/api-reference/request/list-all-messages

get /v1/requests/{request_uid}/messages
Fetch messages

Note: this endpoint will return records with `event_type` being **message** and **notes**

## Usage


# List grouped Requests
Source: https://developer.siit.io/api-reference/request/list-grouped-requests

get /v1/requests/grouped
Fetch Requests with Requests belonging to the same group collapsed into a single Request group entry. Each result is an envelope with a `kind` (`request` or `requests_group`) and the matching `data` payload. Results are scoped to the API key owner's request visibility. `requests_group` counts, tallies and samples are aggregated across the whole group, including requests outside that visibility.



# List Requests
Source: https://developer.siit.io/api-reference/request/list-requests

get /v1/requests
Fetch Requests. Results are scoped to the API key owner's request visibility.

## Usage


# Request an approval
Source: https://developer.siit.io/api-reference/request/request-an-approval

post /v1/requests/{request_uid}/approvals

## Usage


# Retrieve a Request
Source: https://developer.siit.io/api-reference/request/retrieve-a-request

get /v1/requests/{uid}
Fetch a single Request. Requests outside the API key owner's request visibility return a 404.

## Usage


# Send a message
Source: https://developer.siit.io/api-reference/request/send-a-message

post /v1/requests/{request_uid}/messages

## Usage


# Send a private note
Source: https://developer.siit.io/api-reference/request/send-a-private-note

post /v1/requests/{request_uid}/notes

## Usage


# Unarchive a Request
Source: https://developer.siit.io/api-reference/request/unarchive-a-request

patch /v1/requests/{uid}/unarchive
Unarchive a Request. Requests outside the API key owner's request visibility return a 404.

## Usage


# Unset a follower
Source: https://developer.siit.io/api-reference/request/unset-a-follower

delete /v1/requests/{uid}/followers/{follower_uid}
Remove a follower from a Request. Requests outside the API key owner's request visibility, or archived requests, return a 404.

## Usage


# Update a Request
Source: https://developer.siit.io/api-reference/request/update-a-request

put /v1/requests/{uid}
Update a Request. Requests outside the API key owner's request visibility return a 404.

## Usage


# Update assignees
Source: https://developer.siit.io/api-reference/request/update-assignees

patch /v1/requests/{uid}/assignee
Please note that assignee admin must be part of the assignee_inbox. Requests outside the API key owner's request visibility return a 404.

## Usage


# Update status
Source: https://developer.siit.io/api-reference/request/update-status

patch /v1/requests/{uid}/status
Update the status of a Request. Requests outside the API key owner's request visibility return a 404.

## Usage


# Create a Service
Source: https://developer.siit.io/api-reference/service/create-a-service

post /v1/services
Create a Service



# List Services
Source: https://developer.siit.io/api-reference/service/list-services

get /v1/services
Fetch Services

## Usage


# Retrieve a Service
Source: https://developer.siit.io/api-reference/service/retrieve-a-service

get /v1/services/{uid}

## Usage


# Update a Service
Source: https://developer.siit.io/api-reference/service/update-a-service

put /v1/services/{uid}
Update a Service



# List tags
Source: https://developer.siit.io/api-reference/tag/list-tags



## Deprecated

This endpoint cannot be used anymore.
Please use instead endpoints that are specific to the type of tag:

* [List departments](/api-reference/department/list-departments)
* [List legal entities](/api-reference/legal-entity/list-legal-entities)
* [List office locations](/api-reference/office-location/list-office-locations)
* [List request tags](/api-reference/request-tag/list-request-tags)
* [List teams](/api-reference/team/list-teams)
* [List team inboxes](/api-reference/team-inbox/list-team-inboxes)


# Retrieve a tag
Source: https://developer.siit.io/api-reference/tag/retrieve-a-tag



## Deprecated

This endpoint cannot be used anymore.
Please use instead endpoints that are specific to the type of tag:

* [Retrieve a department](/api-reference/department/retrieve-a-department)
* [Retrieve a legal entity](/api-reference/legal-entity/retrieve-a-legal-entity)
* [Retrieve an office location](/api-reference/office-location/retrieve-an-office-location)
* [Retrieve a request tag](/api-reference/request-tag/retrieve-a-request-tag)
* [Retrieve a team](/api-reference/team/retrieve-a-team)
* [Retrieve a team inbox](/api-reference/team-inbox/retrieve-a-team-inbox)


# List Team inboxes
Source: https://developer.siit.io/api-reference/team-inbox/list-team-inboxes

get /v1/team_inboxes
Fetch Team inboxes



# Retrieve a Team inbox
Source: https://developer.siit.io/api-reference/team-inbox/retrieve-a-team-inbox

get /v1/team_inboxes/{uid}



# Create a Team
Source: https://developer.siit.io/api-reference/team/create-a-team

post /v1/teams



# Delete a Team
Source: https://developer.siit.io/api-reference/team/delete-a-team

delete /v1/teams/{uid}



# List Teams
Source: https://developer.siit.io/api-reference/team/list-teams

get /v1/teams
Fetch Teams



# Retrieve a Team
Source: https://developer.siit.io/api-reference/team/retrieve-a-team

get /v1/teams/{uid}



# Update a Team
Source: https://developer.siit.io/api-reference/team/update-a-team

put /v1/teams/{uid}



# Archive a User
Source: https://developer.siit.io/api-reference/user/archive-a-user

patch /v1/users/{uid}/archive



# Create User
Source: https://developer.siit.io/api-reference/user/create-user

post /v1/users

## Introduction

Note: fields that are disabled or restricted to the current user **cannot** be set on creation.

## Usage


# List Users
Source: https://developer.siit.io/api-reference/user/list-users

get /v1/users
Fetch Users

## Introduction

Notes:

1. Fields that are disabled or restricted will *not* be returned.
2. Archived users are **NOT** returned by default.

## Usage


# Merge User
Source: https://developer.siit.io/api-reference/user/merge-user

patch /v1/users/{uid}/merge

Merge the specified user into the one identified by the UID in the path.
All data will be transferred, and the merged user will be permanently deleted.

⚠️ **WARNING**:  This action is irreversible — once completed, the merged user cannot be recovered. ⚠️

## Usage


# Retrieve a User
Source: https://developer.siit.io/api-reference/user/retrieve-a-user

get /v1/users/{uid}

## Introduction

Note: fields that are disabled or restricted to the current user **will not** be returned

## Usage


# Unarchive a User
Source: https://developer.siit.io/api-reference/user/unarchive-a-user

patch /v1/users/{uid}/unarchive

## Usage


# Update a User
Source: https://developer.siit.io/api-reference/user/update-a-user

put /v1/users/{uid}

## Introduction

Note: fields that are disabled or restricted to the current user **will not** be returned

## Usage


# List Workflows
Source: https://developer.siit.io/api-reference/workflow/list-workflows

get /v1/workflows
Fetch Workflows



# Retrieve a Workflow
Source: https://developer.siit.io/api-reference/workflow/retrieve-a-workflow

get /v1/workflows/{uid}
Please note archived Workflows are NOT returned.