Skip to content
JiraVision

API overview

Shape of the API, response envelope, and what it is not.

API overview

What it is

The API is the set of Next.js route handlers under app/api — more than 120 of them. It is the same API the dashboard uses: there is no separate public surface, no version prefix and no API key.

Every route:

  • accepts and returns JSON
  • reads the session from the jv_session cookie, and looks up the auth_sessions row it names
  • is rendered dynamically (no cached responses), so a write is visible on the next read

Response envelope

Success:

{ "success": true, "data": ... }

Some list routes add pagination:

{ "success": true, "data": [...], "pagination": { "page": 1, "pageSize": 10, "total": 138 } }

Failure:

{ "success": false, "message": "Unauthorized" }

A few older routes return { error: "..." } instead; the error-messages doc lists which status codes map to which shape.

Status codes

  • 200 read, 201 create
  • 400 malformed body or a value the model rejects
  • 401 no session: the cookie is absent, or its row is revoked or expired
  • 403 session exists but the role is not allowed
  • 404 the id does not exist
  • 409 a conflict, such as deleting an account that still has open assigned tasks
  • 429 rate limited
  • 500 an unexpected server error; the message field carries the underlying error text
  • 503 the database did not answer, so the session could not be checked — retry, do not sign out

Timestamps

Postgres TIMESTAMP columns are UTC-naive, so the readers project them with to_char into YYYY-MM-DDTHH:MM:SSZ strings. Anything ending in Z from this API is UTC.

What it is not

  • No bearer tokens, no OAuth client credentials, no signed API keys.
  • No public SDK. The examples in these docs are plain fetch calls.
  • No /api/v1 prefix. Paths are exactly the ones listed in the endpoints doc.

Trying it

Signed in, in the browser console of any dashboard page:

const r = await fetch("/api/tasks?pageSize=5")
console.log(await r.json())

The cookie is sent automatically because it belongs to the same origin.