User Stories

REST API — All endpoints require authentication via Bearer token. Include Authorization: Bearer {token} in every request. Tokens are managed in GitScrum Settings → API. Base URL: https://services.gitscrum.com — All request paths in this documentation are relative to this base URL.

User stories represent user-facing requirements or features. Tasks can be grouped under user stories to organize work around deliverable outcomes.

List User Stories

Returns user stories for a project.

GET /user-stories?company_slug={slug}&project_slug={slug}

Query Parameters

Example Request

curl -X GET "https://services.gitscrum.com/user-stories?company_slug=acme&project_slug=web-app" \
  -H "Authorization: Bearer {token}"

Example Response

{
  "data": [
    {
      "slug": "as-a-user-i-can-reset-my-password",
      "title": "As a user, I can reset my password",
      "description": "Users need to recover access when they forget their password.",
      "priority": {
        "id": 2,
        "title": "Medium"
      },
      "acceptance_criteria": "- Reset email sent within 30s\n- Link expires after 24h\n- Password must meet complexity rules",
      "tasks_count": 5,
      "user": {
        "username": "johndoe",
        "name": "John Doe"
      },
      "created_at": "2026-01-15T08:00:00Z"
    }
  ]
}

Get User Story

Returns full details for a single user story.

GET /user-stories/{slug}?company_slug={slug}&project_slug={slug}

Path Parameters

Create User Story

Creates a new user story.

POST /user-stories

Request Body

Example Request

curl -X POST "https://services.gitscrum.com/user-stories" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "As a manager, I can view team velocity",
    "company_slug": "acme",
    "project_slug": "web-app",
    "description": "Managers need a velocity chart to track team output per sprint.",
    "acceptance_criteria": "- Chart shows last 10 sprints\n- Displays story points and task count"
  }'

Update User Story

Updates an existing user story.

PUT /user-stories/{slug}

Request Body

Accepts companyslug, projectslug, and the same optional fields as Create User Story.

Delete User Story

Permanently deletes a user story. Tasks linked to this story are preserved but unlinked.

DELETE /user-stories/{slug}?company_slug={slug}&project_slug={slug}

Path Parameters

Field Reference