Overview

What you can build on Alba Ticket, the three ways in, and a first request in a minute.

Every Alba Ticket workspace can be used by programs as well as by people: scripts, integrations, and AI agents such as Claude, ChatGPT, Cursor or GitHub Copilot. This documentation is for the people who write or configure them, and every workspace serves it at /api/docs, beside the API it describes. For connecting an agent as a member, without writing code, see AI agents in the user guide.

Three ways in

The REST API and the MCP server are switched on separately by an administrator of the workspace, under Administration, Modules and features, and both are off in a new workspace until somebody switches them on. Neither needs the other. A request to one that is off is answered 403 with the code feature_disabled, whatever the token; ask an administrator if you meet it.

The REST API and the MCP server do the same things, with the same rules and the same shapes of data. The MCP tools are the REST endpoints under other names (MCP lists which is which). Both authenticate with a bearer token, which comes either from a member's personal token or from OAuth.

Email is a way in too

Not everything that reaches a workspace from outside is a program with a token. Where the workspace receives email, a reply to a notification becomes a comment on its ticket, mail to a helpdesk form's address raises a request, and a member's own logging address puts a message on the timelines of the contacts it names. For getting a person's answer or a forwarded message into Alba Ticket, that is often all the integration that is needed, and it takes no token: the sender is known by their address, and a reply by the address it was sent to. A mail server of your own can hand messages over by HTTP as well; the technical guide's Incoming email page has the request.

Addresses

Everything is on the workspace's own address, the one people open in their browser. Read on a workspace, these pages use its own address in every example, so a command can be copied as it is:

On the hosted service each workspace has its own address (https://acme.albaticket.com), and each is separate: a token from one workspace means nothing to another. Members find their workspace's addresses on their AI agents page, under Manage AI agents in their account settings.

A program acts as a member

There are no service accounts or API keys that belong to the workspace. Every token stands for one member, and a request made with it is that member's request:

• It sees only the projects, tickets, comments and boards the member can see, including security levels and restricted comments.
• It can do only what the member may do, project by project, and less when the token is read-only.
• Everything it changes is recorded in the ticket's history under the member's name, with the token's name beside it ("Ada Lovelace via Nightly report"), and watchers are notified as for any other change.
• It stops working when the member is deactivated or stops being a member. Customers cannot hold tokens.

To run an integration that should not be tied to a person's own account, invite a member for it (for example build-bot@example.com), log in as it once to make its token, and give it the project roles it needs. It is a member like any other: while it is used, in the browser or through its token, it counts as a seat, as someone using the workspace in a browser does.

Your first request

The REST API has to be switched on for the workspace first (see Three ways in): while it is off, the page below offers no token and every request is answered feature_disabled.

1. Open Manage AI agents in your account settings and, under Personal tokens, create a token with Read and change access. Copy it; it is shown once.
2. Ask who you are:

curl https://your-workspace.albaticket.com/api/v1/me \
  -H "Authorization: Bearer alba_pat_…"

{
  "user": {"id": "5f0c…", "name": "Ada Lovelace"},
  "agent": {"name": "My first token", "access": "write"}
}

3. Find your open tickets:

curl "https://your-workspace.albaticket.com/api/v1/tickets?assignee=me&status=open" \
  -H "Authorization: Bearer alba_pat_…"

4. Create one:

curl https://your-workspace.albaticket.com/api/v1/tickets \
  -H "Authorization: Bearer alba_pat_…" \
  -H "Content-Type: application/json" \
  -d '{"project": "WEB", "summary": "Checkout button misaligned on Safari", "type": "Bug"}'

What is and is not available

Through the API you can read projects, tickets, comments, links, sub-tasks, boards, backlogs and sprints; create, edit, comment on, move, assign and plan tickets; log time; move cards between board columns; create, change, start, complete and delete sprints; record, change, stop and delete activities (activities), list customers and phases, and report hours over a period; read, search, write, move and delete knowledge base pages; and, in the CRM, read, create and change contacts, read and change companies, read and set a deal's fields, log interactions and complete follow-ups.

The API does not delete or archive tickets, link tickets, upload or download attachments, edit or delete comments, comment on, label or restrict knowledge base pages, change a space's settings, vote or watch, create boards or change their settings, make invoices, send email to a contact, record a contact's consent, export or erase a contact, or change anything an administrator configures (projects, workflows, fields, users, customers, contracts). Those stay in the browser.

An administrator can switch a module, or a feature of one, off for the workspace: boards, sprints, the helpdesk, the knowledge base, time and the CRM each have a switch. The endpoints of something that is off answer 403 feature_disabled, its MCP tools are not listed, and what it holds is left out of other answers. The public demo has everything on, the API and MCP included.

This guide

• Authentication: personal tokens, OAuth 2.1 step by step, scopes and lifetimes.
• Requests and errors: formats, how things are named, paging, errors and limits.
• Projects: Tickets and projects, every ticket endpoint with examples, and Boards and sprints, boards, cards, the backlog and the sprint lifecycle.
• Helpdesk: Helpdesk forms, a helpdesk's request types and raising a request of one.
• Knowledge base: Spaces and pages, to read, search, write, move and delete.
• Time: Time tracking, activities, customers, phases and hours, and how time zones work.
• CRM: The CRM, contacts, companies, deals, interactions and follow-ups.
• MCP: the MCP server, its tools and how clients connect.
• Examples: whole scripts to start from.
• API reference: every endpoint with its arguments and answers, where you can try requests with your token.

Every page of this guide is also plain Markdown at its own address with .md added (/api/docs/mcp.md), for an AI assistant to read before it writes a client.