mentio-dev System API

openapi: 3.2.0
info:
  title: Mentio Dev System API
  version: 0.0.1
  description: 'Operations tagged System across 4 of this provider''s published API definitions: api_mentio.json, mentio-dev-api-openapi.json, mentio-dev-app-openapi.json, mentio-dev-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mentio.dev
tags:
- name: System
paths:
  /v1/health:
    get:
      operationId: getHealth
      tags:
      - System
      responses:
        '200':
          description: API is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      summary: Get health
      x-summary-source: derived
    servers:
    - url: https://api.mentio.dev
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key minted via POST /v1/api-keys (format mk_live_...)
x-refined-from:
- api_mentio.json
- mentio-dev-api-openapi.json
- mentio-dev-app-openapi.json
- mentio-dev-openapi.json
x-mentio-errors:
- code: unauthorized
  status: 401
  source: user
  retryable: false
  description: No credential, or one that does not resolve to a workspace.
  fix: 'Send Authorization: Bearer mk_live_… with a key from /api-keys.'
- code: forbidden
  status: 403
  source: user
  retryable: false
  description: The credential is valid but may not do this.
- code: read_only_key
  status: 403
  source: user
  retryable: false
  description: A read key was used on a write endpoint.
  fix: Create a key with write scope.
- code: validation_error
  status: 400
  source: user
  retryable: false
  description: The body or query failed validation; the message names the field.
- code: not_found
  status: 404
  source: user
  retryable: false
  description: No such resource in your workspace. An id from another workspace is a 404, never a 403.
- code: invalid_cursor
  status: 400
  source: user
  retryable: false
  description: The cursor was not one this endpoint issued, or the filters changed between pages.
- code: payload_too_large
  status: 413
  source: user
  retryable: false
  description: The body exceeds the endpoint limit.
- code: rate_limited
  status: 429
  source: user
  retryable: true
  description: The workspace made more than 600 requests in a minute (every key and token together), or hit an endpoint's own cap; Retry-After says when.
  fix: Wait Retry-After seconds and send the same request again. X-RateLimit-Remaining on every response says how much room is left.
- code: duplicate_keyword
  status: 409
  source: user
  retryable: false
  description: The group already tracks this term. A term may be tracked once per group; another group may track it too.
- code: insufficient_balance
  status: 402
  source: user
  retryable: false
  description: The wallet cannot cover one more keyword-day.
  fix: Top up from Billing; tracking resumes on its own.
- code: keyword_limit_reached
  status: 402
  source: user
  retryable: false
  description: The self-serve keyword cap; beyond it is an enterprise conversation.
- code: billing_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no payment provider set up.
- code: schedule_required
  status: 400
  source: user
  retryable: false
  description: A daily alert rule was created without a schedule.
- code: unknown_channel
  status: 400
  source: user
  retryable: false
  description: A rule referenced a channel id the workspace does not own.
- code: not_a_digest
  status: 400
  source: user
  retryable: false
  description: A digest-only action was called on an instant rule.
- code: hourly_email_unsupported
  status: 400
  source: user
  retryable: false
  description: An hourly rule was given an email channel (up to 24 emails a day per rule). Use Slack, Telegram or a webhook, or a daily digest by email.
- code: slack_not_connected
  status: 409
  source: user
  retryable: false
  description: Connect Slack from Settings first. 404 on the Slack connection endpoints, 409 elsewhere.
- code: slack_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Slack app credentials.
- code: telegram_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Telegram bot.
- code: feed_unreadable
  status: 400
  source: user
  retryable: false
  description: No feed was found at the address, or the site blocks automated readers, or it answers an error; the message says which.
- code: feed_login_required
  status: 400
  source: user
  retryable: false
  description: The address answers a sign-in or access-denied page. Send it again with `auth` (the cookie your browser sends to the forum, or one header) to read it signed in.
- code: feed_login_expired
  status: 400
  source: user
  retryable: false
  description: 'The feed still answers a sign-in page with the `auth` sent: copy a fresh cookie from a signed-in browser.'
- code: feed_limit_reached
  status: 409
  source: user
  retryable: false
  description: A workspace reads at most 500 feeds; disconnect one before connecting another.
- code: feed_auth_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no FEED_AUTH_SECRET, so a feed sign-in (auth) cannot be stored encrypted and is refused instead.
- code: email_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no Resend key, so nothing that needs Resend (the audience sync) can run.
- code: invalid_assignee
  status: 400
  source: user
  retryable: false
  description: The assignee id is not a workspace member.
- code: classification_pending
  status: 409
  source: user
  retryable: true
  description: A relevance or sentiment verdict was sent for a mention the classifier has not scored yet.
- code: invalid_member
  status: 400
  source: user
  retryable: false
  description: A person's owner, and the member an outreach activity is credited to, must be workspace members.
- code: already_member
  status: 409
  source: user
  retryable: false
  description: An invitation was sent to an address that already belongs to a member.
- code: last_owner
  status: 409
  source: user
  retryable: false
  description: Removing this member would leave the workspace without an owner.
- code: duplicate_segment
  status: 409
  source: user
  retryable: false
  description: Segment names are unique per workspace.
- code: filter_too_complex
  status: 400
  source: user
  retryable: false
  description: The filters together (lists, anyOf groups, a view or alert rule applied on top) name more values than one query can carry. Shorten the lists or use fewer groups.
- code: duplicate_view
  status: 409
  source: user
  retryable: false
  description: View names are unique per workspace.
- code: duplicate_group
  status: 409
  source: user
  retryable: false
  description: Group names and externalIds are unique per workspace.
- code: default_group
  status: 409
  source: user
  retryable: false
  description: Every workspace keeps one default group, where a keyword lands when no group is named.
- code: default_group_context
  status: 400
  source: user
  retryable: false
  description: 'The default group is the workspace itself: its company is the profile (PATCH /v1/company). A company description goes on any other group.'
- code: group_changed
  status: 409
  source: user
  retryable: false
  description: A keyword was created in or moved into the group while its keywords were being deleted. Its other keywords are gone; retry the delete.
- code: invalid_signature
  status: 401
  source: user
  retryable: false
  description: An inbound webhook did not carry a valid signature.
- code: webhook_not_configured
  status: 503
  source: system
  retryable: false
  description: The inbound webhook has no secret on this deployment.
- code: invalid_token
  status: 400
  source: user
  retryable: false
  description: A signed link (unsubscribe, confirmation) was tampered with or is malformed.
- code: protected_user
  status: 409
  source: user
  retryable: false
  description: Staff accounts cannot be deleted from the admin page.
- code: upstream_unavailable
  status: 502
  source: platform
  retryable: true
  description: A provider (Slack, Telegram, Polar, …) failed while serving your request. Retry with backoff.
- code: internal_error
  status: 500
  source: system
  retryable: false
  description: Something failed on our side. The response carries a requestId; quote it to support.