# Developer API

> A signed, encrypted REST API for reading and writing Orangescrum projects, tasks, timelogs, test cases, defects and checklists.

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/api/introduction

---
The Orangescrum Developer API lets your own systems create and update the same
records your team works with in the browser. It covers projects, tasks,
timelogs, users, the test-case manager, defects and checklists — 59 endpoints in
total, all documented in this reference and published as an
[OpenAPI 3.0 specification](https://v4-api.orangescrum.com/storage/api-docs/partner-v1.json).

> **Availability**
>
> API access is included with **Premium Unlimited** on Orangescrum Cloud. Keys
> are issued from the admin portal — talk to your account manager if you do not
> have one yet. The Community Edition does not ship the Developer API.

## Base URL

All requests go to a single production host:

```
https://v4-api.orangescrum.com
```

Every endpoint lives under `/api/v1/partner/` and is called with `POST`,
including the read operations. Filters, identifiers and pagination all travel in
the request body rather than the query string, because the body is encrypted —
see [Conventions](https://helpdesk.orangescrum.com/guide/api/conventions).

## What a request looks like

Three things happen on every call:

**Encrypt the payload**

    Your parameters are serialised to JSON and encrypted with AES-256-CBC, then
    sent as a single `encrypted_data` field.

**Sign the request**

    You compute an HMAC-SHA256 signature over the method, path, timestamp,
    nonce and body hash, and send it in `X-SIGNATURE`.

**Read the response**

    Responses come back as plain JSON with a `success` flag, a `message`, and a
    `data` object or array.

Both steps are covered in full — with copy-paste code — in
[Authentication](https://helpdesk.orangescrum.com/guide/api/authentication).

## A first call

`/api/v1/partner/validate` exists purely so you can prove your credentials work
before writing any real integration. It takes no payload.

```bash
curl -X POST 'https://v4-api.orangescrum.com/api/v1/partner/validate' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: pk_your_api_key' \
  -H 'X-TIMESTAMP: 1704806400' \
  -H 'X-NONCE: b7f91c2e5a8d3f1e' \
  -H 'X-SIGNATURE: <hmac-sha256>'
```

A success response confirms the key, its scopes and the server's clock:

```json
{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "partner_id": 42,
    "api_key_id": 7,
    "scopes": ["*"],
    "timestamp": 1704806400
  }
}
```

## What you can reach

- [Projects](https://helpdesk.orangescrum.com/guide/api/endpoints/projects/projects-list): List, create, update, search and inspect projects.

- [Tasks](https://helpdesk.orangescrum.com/guide/api/endpoints/tasks/tasks-list): Full CRUD plus search across every task in the workspace.

- [Timelogs](https://helpdesk.orangescrum.com/guide/api/endpoints/timelogs/timelogs-list): Read and write time entries against tasks and projects.

- [Users](https://helpdesk.orangescrum.com/guide/api/endpoints/users/users-list): Read the workspace directory and individual user records.

- [Test management](https://helpdesk.orangescrum.com/guide/api/endpoints/test-cases/test-cases-list): Test cases, scenarios and steps from the Test Case Manager.

- [Defects](https://helpdesk.orangescrum.com/guide/api/endpoints/defects/defects-list): Raise defects, link them to test entities and move their status.

## Prefer an AI assistant?

The same API is exposed as a Model Context Protocol server, so Claude, Cursor,
GitHub Copilot and the Codex CLI can call it directly with the key you already
have. See [MCP / AI Connect](https://helpdesk.orangescrum.com/guide/mcp/introduction).

## Next steps

- [Authentication](https://helpdesk.orangescrum.com/guide/api/authentication): Generate the signature and encrypt your payload.

- [Conventions](https://helpdesk.orangescrum.com/guide/api/conventions): Identifiers, pagination, dates and the response envelope.