OpenAPI (Swagger)

Overview

This section presents the backend OpenAPI specification for Raccoon Survey. From this document, HTTP endpoints are generated and documented together with their parameters, request/response bodies, status codes, and data schemas. The source specification lives in src/core/openapi.json and acts as the integration contract for external clients and validation tools.

How to Read and Use

  • Endpoints are grouped by tags for easier navigation.

  • Each endpoint details the HTTP method, path, parameters, request body, responses, and schemas.

  • Use this page as a reference when integrating, testing, or validating API behavior.

Common Conventions

  • Set Content-Type: application/json for JSON requests.

  • Use Authorization: Bearer <token> for endpoints that require authentication.

  • Error responses include clear codes and messages aligned with the schema definitions.

Quickstart with curl

Authenticate and call typical endpoints from the command line.

# 1) Login (replace credentials if needed)
curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@docs.local","password":"pass_doc_local"}'

# 2) Capture access token (requires jq)
TOKEN=$(curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@docs.local","password":"pass_doc_local"}' | jq -r '.access_token')

# 3) Authenticated profile
curl -s http://localhost:3000/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

# 4) List surveys
curl -s http://localhost:3000/api/v1/surveys \
  -H "Authorization: Bearer $TOKEN"

# 5) Create a survey (example payload)
curl -s -X POST http://localhost:3000/api/v1/surveys \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"title":"Quarterly Satisfaction","team_id":1}'

Tip

On Windows PowerShell, replace environment variables with $env:TOKEN and use backticks or backquotes to escape.

Postman Collection

Use the shared Postman collection for ready-to-run requests and environments:

Rendered Specification

POST /auth/login

Login

Status Codes:
GET /auth/me

User profile

Status Codes:
GET /surveys
Status Codes:
POST /surveys
Status Codes:
GET /surveys/{survey_id}
Parameters:

  • survey_id (integer)

Status Codes:
PUT /surveys/{survey_id}
Parameters:

  • survey_id (integer)

Status Codes:
PATCH /surveys/{survey_id}/state
Parameters:

  • survey_id (integer)

Status Codes:
GET /questions
Status Codes:
POST /questions
Status Codes:
GET /questions/{question_id}
Parameters:

  • question_id (integer)

Status Codes:
PUT /questions/{question_id}
Parameters:

  • question_id (integer)

Status Codes:
PATCH /questions/{question_id}/state
Parameters:

  • question_id (integer)

Status Codes:
GET /teams
Status Codes:
POST /teams
Status Codes:
GET /teams/{team_id}
Parameters:

  • team_id (integer)

Status Codes:
PUT /teams/{team_id}
Parameters:

  • team_id (integer)

Status Codes:
PATCH /teams/{team_id}/state
Parameters:

  • team_id (integer)

Status Codes:
POST /tokens/{survey_id}/generate
Parameters:

  • survey_id (integer)

Status Codes:
GET /tokens/{survey_id}/list
Parameters:

  • survey_id (integer)

Query Parameters:

  • is_used (boolean)

  • include_expired (boolean)

Status Codes:
GET /tokens/{survey_id}/export
Parameters:

  • survey_id (integer)

Query Parameters:

  • is_used (boolean)

  • include_expired (boolean)

Status Codes:
POST /anonymous/responses

Submit anonymous responses

Status Codes:
GET /anonymous/resolve

Resolve survey by token

Query Parameters:

  • token (string) – (Required)

  • survey_id (integer)

Status Codes:
POST /auth/logout

Logout and revoke token

Status Codes:
POST /auth/refresh

Refresh access token

Status Codes:
GET /metrics/dashboard
Status Codes:
GET /reports/surveys/{survey_id}/summary
Parameters:

  • survey_id (integer)

Query Parameters:

  • team_id (integer)

  • date_from (string)

  • date_to (string)

Status Codes:
GET /reports/teams/{team_id}/summary
Parameters:

  • team_id (integer)

Query Parameters:

  • survey_id (integer)

  • date_from (string)

  • date_to (string)

Status Codes:
GET /reports/export
Query Parameters:

  • survey_id (integer)

  • team_id (integer)

  • date_from (string)

  • date_to (string)

Status Codes:
POST /maintenance/tokens/cleanup
Status Codes: