rumoro-dev System API

openapi: 3.2.0
info:
  title: Rumoro System API
  version: 0.0.1
  description: Social listening for developers and AI agents.
servers:
- url: https://api.rumoro.dev
tags:
- name: System
paths:
  /v1/health:
    get:
      operationId: getHealth
      description: 'Checks that the API is up. Needs no key and is not rate limited. Returns `ok: true` with the state of the database and each background worker.'
      tags:
      - System
      responses:
        '200':
          description: The API is running
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                required:
                - ok
      summary: Get health
      x-summary-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key from POST /v1/api-keys. Keys start with ref_.
x-rumoro-errors:
- code: unauthorized
  status: 401
  source: user
  retryable: false
  description: The credential is missing or does not belong to a workspace.
  fix: 'Send Authorization: Bearer ref_… with a key from /api-keys.'
- code: forbidden
  status: 403
  source: user
  retryable: false
  description: The credential works but is not allowed to do this.
- code: read_only_key
  status: 403
  source: user
  retryable: false
  description: A read-only key called an endpoint that writes.
  fix: Create a key with write scope.
- code: validation_error
  status: 400
  source: user
  retryable: false
  description: The body or query is not valid. The message says which field.
- code: not_found
  status: 404
  source: user
  retryable: false
  description: Your workspace has nothing with this id. An id from another workspace also returns 404, never 403.
- code: invalid_cursor
  status: 400
  source: user
  retryable: false
  description: The cursor could not be read, or was issued for another sort. Start again from the first page.
- code: payload_too_large
  status: 413
  source: user
  retryable: false
  description: 'The body exceeds the endpoint limit (128 KiB for JSON). A 409 with this code: a delivery whose payload was too large cannot be retried or replayed.'
- code: rate_limited
  status: 429
  source: user
  retryable: true
  description: The workspace sent over 600 requests in a minute across all its keys and tokens, or reached an endpoint's own limit. Retry-After and error.retryAfterSeconds tell you when to try again.
  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: This group already has the term. Each group can hold a term once, and other groups can hold it too.
- code: insufficient_balance
  status: 402
  source: user
  retryable: false
  description: The balance cannot pay for 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 workspace already runs 500 keywords, or has 500 that are not deleted.
- code: billing_not_configured
  status: 503
  source: system
  retryable: false
  description: No payment provider is set up on this deployment.
- code: unknown_channel
  status: 400
  source: user
  retryable: false
  description: An alert named a channel id that is not in this workspace.
- code: not_a_digest
  status: 400
  source: user
  retryable: false
  description: An action for digests was used on an instant alert.
- code: hourly_email_unsupported
  status: 400
  source: user
  retryable: false
  description: An hourly alert got an email channel, which could mean 24 emails a day. Use Slack, Telegram or a webhook, or send a daily digest by email.
- code: slack_not_connected
  status: 409
  source: user
  retryable: false
  description: Slack must be connected in Settings first. Returned as 404 by the Slack connection endpoints and 409 elsewhere.
- code: slack_not_configured
  status: 503
  source: system
  retryable: false
  description: No Slack app is set up on this deployment.
- code: telegram_not_configured
  status: 503
  source: system
  retryable: false
  description: No Telegram bot is set up on this deployment.
- code: email_not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no email sender set up, so email destinations cannot be used.
- code: invalid_assignee
  status: 400
  source: user
  retryable: false
  description: The assignee is not in the workspace.
- code: classification_pending
  status: 409
  source: user
  retryable: true
  description: Relevance or sentiment feedback was sent before the classifier scored the mention.
- code: already_member
  status: 409
  source: user
  retryable: false
  description: The invited address already belongs to a member.
- code: last_owner
  status: 409
  source: user
  retryable: false
  description: The workspace would have no owner left after this removal.
- code: duplicate_segment
  status: 409
  source: user
  retryable: false
  description: Another segment in the workspace has this name.
- code: duplicate_view
  status: 409
  source: user
  retryable: false
  description: Another view in the workspace has this name.
- code: duplicate_group
  status: 409
  source: user
  retryable: false
  description: Another group in the workspace has this name or externalId.
- code: default_group
  status: 409
  source: user
  retryable: false
  description: The default group cannot be deleted. It holds keywords created without a group.
- code: default_group_context
  status: 400
  source: user
  retryable: false
  description: The default group uses the workspace's company profile, which you change with PATCH /v1/company. Only other groups can have their own description.
- code: invalid_signature
  status: 401
  source: user
  retryable: false
  description: An incoming webhook had no valid signature.
- code: invalid_token
  status: 400
  source: user
  retryable: false
  description: A signed link (unsubscribe, confirmation, preferences) was tampered with or is malformed.
- code: upstream_unavailable
  status: 502
  source: platform
  retryable: true
  description: An outside service such as Slack or Polar failed during the request. Retry with increasing waits.
- code: internal_error
  status: 500
  source: system
  retryable: false
  description: Something failed on our side; 502 when Telegram failed a bot lookup. The response carries a requestId; quote it to support.
- code: unsupported_media_type
  status: 415
  source: user
  retryable: false
  description: 'A body was sent without Content-Type: application/json.'
- code: request_timeout
  status: 408
  source: user
  retryable: true
  description: The body did not arrive within 5 seconds.
- code: key_limit
  status: 409
  source: user
  retryable: false
  description: The workspace already has 100 active keys. Revoke one first.
- code: conflict
  status: 409
  source: user
  retryable: false
  description: A resource with these values already exists.
- code: no_billing_owner
  status: 404
  source: user
  retryable: false
  description: There is no owner to bill in this workspace yet.
- code: rule_disabled
  status: 409
  source: user
  retryable: false
  description: The rule is turned off. Enable it before a test or a run.
- code: no_channels
  status: 409
  source: user
  retryable: false
  description: The rule has no destination to test.
- code: channel_disabled
  status: 409
  source: user
  retryable: false
  description: A destination is turned off. Enable it first.
- code: no_recipients
  status: 409
  source: user
  retryable: false
  description: An email destination needs a recipient before it can be turned on.
- code: recipient_suppressed
  status: 409
  source: user
  retryable: false
  description: The address bounced or complained, so no more email goes to it.
- code: confirmation_rate_limited
  status: 429
  source: user
  retryable: true
  description: 'Too many confirmation emails: wait a minute; at most three per address a day and twenty per workspace an hour.'
- code: confirmation_requires_resend
  status: 409
  source: user
  retryable: false
  description: A confirmation email is sent again with a resend, not a delivery retry.
- code: email_test_rate_limited
  status: 429
  source: user
  retryable: true
  description: More than five email tests on this destination this hour.
- code: email_hourly_limit
  status: 409
  source: user
  retryable: false
  description: The destination's hourly email limit is reached; the mention waits for the next daily digest.
- code: email_idempotency_expired
  status: 409
  source: user
  retryable: false
  description: The email's safe retry window passed. Check its receipts before an explicit replay, which may send it twice.
- code: email_transport_unavailable
  status: 503
  source: system
  retryable: false
  description: Email sending is not set up for this delivery on this deployment.
- code: delivery_not_configured
  status: 503
  source: system
  retryable: false
  description: Destinations that need a stored secret are not set up on this deployment.
- code: delivery_key_unavailable
  status: 503
  source: system
  retryable: false
  description: A destination's stored secret cannot be read on this deployment.
- code: not_retryable
  status: 409
  source: user
  retryable: false
  description: Only failed or blocked deliveries can be retried.
- code: not_replayable
  status: 409
  source: user
  retryable: false
  description: A delivery can be replayed once it has finished.
- code: digest_has_replay
  status: 409
  source: user
  retryable: false
  description: This digest delivery has a newer replay. Recover that one.
- code: digest_retry_expired
  status: 409
  source: user
  retryable: false
  description: The digest's six-hour retry window passed. Replay it instead.
- code: delivery_request_incomplete
  status: 500
  source: system
  retryable: true
  description: The saved outcome of a test could not be read. Read it again; don't send a new test.
- code: request_conflict
  status: 409
  source: user
  retryable: false
  description: This requestId was already used for another request. Retry the original, or use a new id.
- code: stale_version
  status: 409
  source: user
  retryable: false
  description: The resource changed since you read it. Read it again before saving.
- code: version_conflict
  status: 409
  source: user
  retryable: true
  description: The webhook's managed rules changed at the same time. Read it again and retry.
- code: already_classified
  status: 409
  source: user
  retryable: false
  description: The mention is already scored; there is nothing to retry.
- code: keyword_inactive
  status: 409
  source: user
  retryable: false
  description: The mention's keyword is paused. Resume it before retrying the score.
- code: source_unavailable
  status: 502
  source: platform
  retryable: true
  description: 'Live search: the platform didn''t answer (503 when it is rate limiting us).'
- code: source_timeout
  status: 504
  source: platform
  retryable: true
  description: 'Live search: the platform didn''t answer in time.'
- code: invalid_host
  status: 403
  source: user
  retryable: false
  description: 'MCP: the request''s Host is not this server''s.'
- code: invalid_origin
  status: 403
  source: user
  retryable: false
  description: 'MCP: the request''s Origin is not allowed.'
- code: database_unavailable
  status: 503
  source: system
  retryable: true
  description: A temporary database problem. Retry with backoff.
- code: database_not_ready
  status: 503
  source: system
  retryable: false
  description: The deployment's database needs maintenance; retrying won't help until it is done.
- code: not_configured
  status: 503
  source: system
  retryable: false
  description: This deployment has no database configured.