# BARD Tracker

> Project management for software teams. Tracks tickets, epics, velocity, and delivery timelines.

## API Documentation

- OpenAPI 3.0.3 spec (machine-readable): https://bardtracker.com/api/docs/v1/swagger.yaml
- Interactive Swagger UI: https://bardtracker.com/api/docs

## Authentication

All API requests require a Bearer token in the Authorization header:

    Authorization: Bearer YOUR_API_TOKEN

API tokens are 64-character hex strings. Each user has one, found in their account settings.

Unauthenticated requests return 401. Requests to projects the user doesn't belong to return 403.

## Base URL

    https://bardtracker.com/api/v1

## Endpoints

### Projects

    GET /api/v1/projects              List projects accessible to the authenticated user
    GET /api/v1/projects/{id}         Get project details (includes ticket_count, epic_count)

### Tickets (BARD native)

    GET    /api/v1/projects/{id}/tickets          List tickets (filter: ?state=unstarted)
    POST   /api/v1/projects/{id}/tickets          Create a ticket
    GET    /api/v1/projects/{id}/tickets/{tid}     Get ticket details (tasks, comments, blockers)
    PUT    /api/v1/projects/{id}/tickets/{tid}     Update a ticket (state, title, position, labels, owners)
    DELETE /api/v1/projects/{id}/tickets/{tid}     Delete a ticket

### Stories (Pivotal Tracker compatible aliases)

Same operations as tickets, at /api/v1/projects/{id}/stories. Both endpoints return identical responses.

## Ticket Fields

Responses include both Pivotal Tracker field names and BARD aliases:

| Pivotal field   | BARD alias   | Description                                          |
|-----------------|--------------|------------------------------------------------------|
| name            | title        | Ticket title                                         |
| story_type      | ticket_type  | feature, bug, chore, or release                      |
| current_state   | state        | unstarted, started, finished, delivered, accepted, rejected |
| estimate        | estimate     | Point estimate (integer or null)                     |
| description     | description  | Body text                                            |
| owner_ids       | owner_ids    | Array of assignee user IDs                           |
| requested_by_id | requested_by_id | Requester user ID                                 |
| labels          | labels       | Array of {id, name} objects                          |

## Creating and Updating Tickets

POST and PUT accept JSON with these fields:

    {
      "name": "Ticket title",
      "story_type": "feature",
      "current_state": "unstarted",
      "description": "Details...",
      "estimate": 3,
      "owner_ids": [1, 2],
      "requested_by_id": 1,
      "labels": [{"name": "urgent"}, {"name": "api"}],
      "before_id": 123,
      "after_id": 456
    }

- `before_id` / `after_id` position the ticket relative to another ticket (for prioritization).
- `labels` replaces all existing labels on update.
- `story_type` values: feature, bug, chore, release.
- `current_state` transitions: unstarted -> started -> finished -> delivered -> accepted (or rejected -> started).

### Epics

    GET    /api/v1/projects/{id}/epics          List epics (filter: ?completed=true/false)
    POST   /api/v1/projects/{id}/epics          Create an epic
    GET    /api/v1/projects/{id}/epics/{eid}     Get epic details (comments)
    PUT    /api/v1/projects/{id}/epics/{eid}     Update an epic (name, description, label, position)
    DELETE /api/v1/projects/{id}/epics/{eid}     Delete an epic

### Iterations

    GET /api/v1/projects/{id}/iterations     Velocity summary + iteration projections

## Epic Fields

Responses include Pivotal Tracker field names and BARD extensions:

| Field           | Description                                          |
|-----------------|------------------------------------------------------|
| name            | Epic name (Pivotal field)                            |
| title           | Epic name (BARD alias)                               |
| description     | Body text                                            |
| label           | Nested label object {id, name, kind}                 |
| label_id        | Label ID (integer)                                   |
| completed       | Whether all tickets are accepted (boolean)           |
| position        | Ordering position (integer)                          |
| tickets_count   | Total ticket count                                   |
| accepted_count  | Accepted ticket count                                |
| started_count   | Started ticket count                                 |
| unstarted_count | Unstarted ticket count                               |
| url             | Direct link to epic in BARD Tracker                  |
| kind            | Always "epic"                                        |

Detail responses (GET by ID) also include `comments` and `comment_ids`.

## Iterations

Returns a velocity summary with iteration projections. Response is a single object (not an array).

Top-level fields:

| Field                    | Description                                           |
|--------------------------|-------------------------------------------------------|
| velocity                 | Current velocity (integer, null if velocity disabled)  |
| velocity_enabled         | Whether velocity tracking is enabled (boolean)        |
| points_scale             | Points scale name (e.g. Fibonacci, Pivotal, None)     |
| iteration_length_weeks   | Iteration length in weeks (integer)                   |
| current_iteration_number | Current iteration number (integer)                    |
| iterations               | Array of iteration objects (past, current, projected) |

Iteration object fields (Pivotal field + BARD alias):

| Pivotal field | BARD alias       | Description                                    |
|---------------|------------------|------------------------------------------------|
| start         | start_date       | Iteration start date                           |
| finish        | end_date         | Iteration end date                             |
| length        | iteration_length | Iteration length in weeks                      |
| number        | number           | Iteration sequence number                      |
| velocity      | velocity         | Velocity for this iteration                    |
| team_strength | —                | Always 1.0 (Pivotal compatibility)             |
| kind          | —                | Always "iteration"                             |
| —             | points           | Accepted points                                |
| —             | projected_points | Projected total points                         |
| —             | current_points   | Points in progress (current iteration only)    |
| —             | complete         | Whether iteration is complete (boolean)        |
| —             | ticket_count     | Number of tickets in iteration                 |

## Creating and Updating Epics

POST and PUT accept JSON with these fields:

    {
      "name": "Epic title",
      "description": "Details...",
      "label": {"name": "custom-label"},
      "before_id": 123,
      "after_id": 456
    }

- `name` is required on create.
- `label` is a single label object (epics have one label). If omitted on create, defaults to the epic name.
- `before_id` / `after_id` position the epic relative to another epic.

## Response Format

List endpoints return JSON arrays. Detail endpoints return JSON objects. Errors return:

    {"error": "Error message"}

Status codes: 200 (success), 201 (created), 204 (deleted), 401 (unauthorized), 403 (forbidden), 404 (not found), 422 (validation error).