HTTP API Contract (OpenAPI)

This page renders the source contract from documentation/static/openapi.yml.yaml.

Keep this contract synchronized with code changes. If request/response payloads, status codes, or authentication behavior change, update the OpenAPI file in the same pull request.

• Health
  • getCheck service liveness and current API version
• Prompts
  • getFetch the active daily prompt and response window metadata
• Submissions
  • postCreate a user submission for the active prompt window
• Admin
  • postForce-send a prompt to a target channel outside normal schedule
• Metrics
  • getRetrieve prompt metrics for a workspace

API docs by Redocly

VibeCheck HTTP API (0.1.0-draft)

Download OpenAPI specification:Download

VibeCheck Team: support@example.com License: MIT

Contract-first HTTP API for VibeCheck.

Note: the current repository runtime uses Slack Socket Mode, so these HTTP routes represent the planned external contract for a REST deployment profile.

Health

Service availability and diagnostics

Check service liveness and current API version

Responses

Local development

http://localhost:8000/health

Production

https://api.vibecheck.example.com/health

Response samples

• 200

Content type

application/json

{

• "status": "ok",
• "service": "vibecheck-backend",
• "version": "0.1.0",
• "timestamp": "2026-03-30T12:30:15Z"

}

Prompts

Prompt retrieval and dispatch operations

Fetch the active daily prompt and response window metadata

Authorizations:

bearerAuth

Responses

Local development

http://localhost:8000/v1/prompts/today

Production

https://api.vibecheck.example.com/v1/prompts/today

Response samples

• 200
• 401
• 500

Content type

application/json

{

• "promptId": "prm_20260330",
• "text": "Post a quick lunch update and a photo.",
• "channelId": "C01234567",
• "opensAt": "2026-03-30T16:00:00Z",
• "closesAt": "2026-03-30T16:30:00Z",
• "status": "active"

}

Submissions

User submission APIs

Create a user submission for the active prompt window

Authorizations:

bearerAuth

Request Body schema: application/json

userId required	string
channelId required	string
text required	string [ 1 .. 1000 ] characters
imageUrl	string <uri>

Responses

Local development

http://localhost:8000/v1/submissions

Production

https://api.vibecheck.example.com/v1/submissions

Request samples

• Payload

Content type

application/json

{

• "userId": "U12345",
• "channelId": "C01234567",
• "text": "Lunch break at the student center",
• "imageUrl": "https://cdn.example.com/images/submission1.jpg"

}

Response samples

• 201
• 400
• 401
• 409
• 500

Content type

application/json

{

• "submissionId": "sub_4f8128",
• "promptId": "prm_20260330",
• "userId": "U12345",
• "channelId": "C01234567",
• "text": "Lunch break at the student center",
• "imageUrl": "https://cdn.example.com/images/submission1.jpg",
• "createdAt": "2026-03-30T16:11:33Z",
• "late": false

}

Admin

Admin-only control operations

Force-send a prompt to a target channel outside normal schedule

Authorizations:

bearerAuth

Request Body schema: application/json

channelId required	string
promptText required	string non-empty
postImmediately	boolean Default: true

Responses

Local development

http://localhost:8000/v1/admin/prompts/force-send

Production

https://api.vibecheck.example.com/v1/admin/prompts/force-send

Request samples

• Payload

Content type

application/json

{

• "channelId": "string",
• "promptText": "string",
• "postImmediately": true

}

Response samples

• 202
• 400
• 401
• 403
• 500

Content type

application/json

{

• "accepted": true,
• "requestId": "string"

}

Metrics

Prompt usage and response-count reporting

Retrieve prompt metrics for a workspace

Authorizations:

bearerAuth

query Parameters

teamId required	string Slack workspace identifier whose metrics should be returned
limit	integer [ 1 .. 100 ] Default: 20 Maximum number of prompt metric rows to return

Responses

Local development

http://localhost:8000/v1/metrics/prompts

Production

https://api.vibecheck.example.com/v1/metrics/prompts

Response samples

• 200
• 400
• 401
• 500

Content type

application/json

{

• "teamId": "T12345",
• "count": 2,
• "items": [

  • {

    • "promptId": "5",
    • "prompt": "If you had to swap jobs with a friend for a day, who would it be?",
    • "tags": [

      • "work_life"

      ],
    • "timesAsked": 8,
    • "timesResponded": 5,
    • "lastAskedAt": "2026-04-13T18:30:00Z"

    },
  • {

    • "promptId": "12",
    • "prompt": "Post a photo that captures your current energy.",
    • "tags": [

      • "photo",
      • "social"

      ],
    • "timesAsked": 6,
    • "timesResponded": 2,
    • "lastAskedAt": "2026-04-12T18:30:00Z"

    }

  ]

}