# Mehashi API — guide for AI agents

Mehashi is a lightweight project-management workspace for startups; free for up
to 5 people, then £1/$1/€1 per seat per month. This guide tells an AI agent (or
any HTTP client) how to authenticate and work a user's board via the API. For
what the product is, what it costs, and the rest of the site, see
https://mehashi.com/llms.txt.

Base URL: https://api.mehashi.com
Format:   JSON over HTTPS. Send `content-type: application/json` on requests
          with a body.

## Authentication

The API uses cookie sessions. There are no API tokens yet.

1. POST /auth/login with `{"email": "...", "password": "..."}`.
   A successful response sets an httpOnly session cookie.
2. Send that cookie on every subsequent request (curl: `-c cookies.txt` on
   login, then `-b cookies.txt`; fetch: `credentials: "include"`).
3. POST /auth/logout ends the session.

Never ask the user to paste their password into chat; have them run the login
step themselves, or run it in a tool that keeps credentials out of the
transcript. Requests are authorized as the signed-in user — the API can see and
change exactly what that user can in the app.

## Orientation: find ids first

- GET /me
  Returns the current user and their workspace memberships
  (`memberships[].org.id`).
- GET /projects
  Projects the user belongs to. Also: GET /orgs/{orgId}/projects.
- GET /projects/{projectId}
  One project, including its board columns.

Resource hierarchy: org (workspace) → project → tasks (tickets), with board
columns, members, assignees, comments, and subtasks hanging off projects/tasks.

## Tickets (tasks)

- GET /projects/{projectId}/tasks
  List tickets, newest first. Optional filter: ?status=todo|inprogress|check|done
- POST /projects/{projectId}/tasks
  Create a ticket. Body: `{"title": "..."}` (required, ≤500 chars) plus
  optional `status`, `columnId`, `text` (description, ≤5000 chars), `label`,
  `labelColor` (slate|sky|emerald|amber|rose|violet), `startDate`, `dueDate`
  (ISO 8601), `assigneeIds` (project member user ids).
- PATCH /tasks/{taskId}
  Update any subset of the same fields, e.g. `{"status": "done"}` or
  `{"title": "New title", "text": "New description"}`. Provide at least one
  field. Set `label` to null to clear it.
- DELETE /tasks/{taskId}
  Delete a ticket (204, no body).

Statuses: todo, inprogress, check (ready for review), done.
Boards may have custom columns: pass `columnId` (from the project's
board-columns) instead of `status` when creating or moving a ticket —
`columnId` takes precedence.

## Assignees, comments, subtasks

- POST   /tasks/{taskId}/assignees            body `{"userId": "..."}`
- DELETE /tasks/{taskId}/assignees/{userId}
- GET    /tasks/{taskId}/comments
- POST   /tasks/{taskId}/comments             body `{"body": "..."}`
- GET    /tasks/{taskId}/subtasks
- POST   /tasks/{taskId}/subtasks             body `{"title": "..."}`
- PATCH  /tasks/{taskId}/subtasks/{subtaskId} body `{"completed": true}`

Assignees must already be project members (see
GET /projects/{projectId}/members).

## Projects & members

- POST /projects                          body `{"orgId": "...", "name": "..."}`
- GET  /projects/{projectId}/board-columns
- GET  /projects/{projectId}/members
- POST /projects/{projectId}/members      body `{"userId": "..."}`

## Errors

Errors return a matching HTTP status and a JSON body:
`{"error": "machine_code", "message": "Human-readable explanation"}`.
401 means the session cookie is missing/expired — log in again.
403 means the user lacks access to that resource. Respect 4xx responses;
do not retry them unchanged.

## Worked example

# 1. Sign in (saves cookie)
curl -c cookies.txt -X POST https://api.mehashi.com/auth/login \
  -H "content-type: application/json" \
  -d '{"email":"you@company.com","password":"..."}'

# 2. Find a project id
curl -b cookies.txt https://api.mehashi.com/projects

# 3. Create a ticket
curl -b cookies.txt -X POST https://api.mehashi.com/projects/PROJECT_ID/tasks \
  -H "content-type: application/json" \
  -d '{"title":"Fix login redirect","status":"todo"}'

# 4. Move it to done
curl -b cookies.txt -X PATCH https://api.mehashi.com/tasks/TASK_ID \
  -H "content-type: application/json" \
  -d '{"status":"done"}'

Webhooks and personal API tokens are not available yet; poll
GET /projects/{projectId}/tasks to observe changes.