rumoro-dev Filters API

openapi: 3.2.0
info:
  title: Rumoro Filters API
  version: 0.0.1
  description: Social listening for developers and AI agents.
servers:
- url: https://api.rumoro.dev
tags:
- name: Filters
paths:
  /v1/filters:
    get:
      operationId: getFilters
      summary: Get the workspace filters
      description: Returns the workspace noise rules, applied to every keyword before a mention is stored. They exclude terms, authors and GitHub repositories, and allow or block subreddits. Rejected posts are never classified, sent or billed. Keywords add their own `matching` rules on top.
      tags:
      - Filters
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The workspace's filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceFilters'
        '401':
          description: The API key is missing or not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: updateFilters
      summary: Update the workspace filters
      description: Sets new values for any of the lists. A list you leave out stays as it is, and an empty list clears it. Rumoro normalizes each entry. Terms become lowercase, authors profile links or plain names, repositories owner/name, and subreddits lose the r/. New mentions follow the change within a minute. Stored mentions stay as they are.
      tags:
      - Filters
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                excludedTerms:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 80
                  maxItems: 200
                  description: Sets a new list. An empty list clears it.
                excludedAuthors:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 500
                  maxItems: 200
                  description: Sets a new list. An empty list clears it.
                excludedRepos:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 200
                  maxItems: 200
                  description: Sets a new list. An empty list clears it.
                subreddits:
                  type: object
                  properties:
                    only:
                      type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 100
                      maxItems: 200
                      description: Sets a new list of allowed subreddits. An empty list clears it.
                    excluded:
                      type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 100
                      maxItems: 200
                      description: Sets a new list of blocked subreddits. An empty list clears it.
                  description: Applies to Reddit only. A list you leave out stays as it is.
              description: Fields you leave out stay as they are. An empty list clears a field.
      responses:
        '200':
          description: The filters after the change
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceFilters'
        '400':
          description: Could not parse an entry as a term, author, repository or subreddit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The API key is missing or not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - forbidden
              - read_only_key
              - validation_error
              - not_found
              - invalid_cursor
              - payload_too_large
              - rate_limited
              - duplicate_keyword
              - insufficient_balance
              - keyword_limit_reached
              - billing_not_configured
              - unknown_channel
              - not_a_digest
              - hourly_email_unsupported
              - slack_not_connected
              - slack_not_configured
              - telegram_not_configured
              - email_not_configured
              - invalid_assignee
              - classification_pending
              - already_member
              - last_owner
              - duplicate_segment
              - duplicate_view
              - duplicate_group
              - default_group
              - default_group_context
              - invalid_signature
              - invalid_token
              - upstream_unavailable
              - internal_error
              - unsupported_media_type
              - request_timeout
              - key_limit
              - conflict
              - no_billing_owner
              - rule_disabled
              - no_channels
              - channel_disabled
              - no_recipients
              - recipient_suppressed
              - confirmation_rate_limited
              - confirmation_requires_resend
              - email_test_rate_limited
              - email_hourly_limit
              - email_idempotency_expired
              - email_transport_unavailable
              - delivery_not_configured
              - delivery_key_unavailable
              - not_retryable
              - not_replayable
              - digest_has_replay
              - digest_retry_expired
              - delivery_request_incomplete
              - request_conflict
              - stale_version
              - version_conflict
              - already_classified
              - keyword_inactive
              - source_unavailable
              - source_timeout
              - invalid_host
              - invalid_origin
              - database_unavailable
              - database_not_ready
              - not_configured
              description: A stable code for programs. Branch on it, not on the message. New codes may be added, so treat an unknown one as a general failure with the same status.
            message:
              type: string
              description: A description for people. Its wording can change.
            requestId:
              type: string
              description: This request's id, also sent in the X-Request-Id header. Include it when you contact support.
            retryAfterSeconds:
              type: integer
              description: Seconds to wait before retrying, on rate_limited and other errors you can retry. Same value as the Retry-After header.
          required:
          - code
          - message
          description: Details of the error.
      required:
      - error
    WorkspaceFilters:
      type: object
      properties:
        excludedTerms:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 80
          maxItems: 200
          description: Posts that contain one of these terms are dropped, whichever keyword matched them. Terms follow the same phrase rule as a keyword, and `*` at either end is a wildcard. A common list is "hiring, job, careers".
        excludedAuthors:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 500
          maxItems: 200
          description: Authors ignored across all keywords, such as your own accounts, teammates or known spammers. Entries may be profile or post links, @handles, u/names, Bluesky DIDs or display names, and are saved in canonical form.
        excludedRepos:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 200
          maxItems: 200
          description: Repositories to ignore, as owner/name or a github.com link (vercel/next.js, https://github.com/vercel/next.js). Their issues, pull requests and comments are dropped.
        subreddits:
          type: object
          properties:
            only:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 100
              maxItems: 200
              description: Allowlist of subreddits (r/name or name). When set, other subreddits are dropped and `excluded` is ignored.
            excluded:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 100
              maxItems: 200
              description: Subreddits to ignore, written as r/name or name.
          required:
          - only
          - excluded
          description: Applies to Reddit only.
        updatedAt:
          type:
          - string
          - 'null'
          description: When the filters were last changed. Null if never.
      required:
      - excludedTerms
      - excludedAuthors
      - excludedRepos
      - subreddits
      - updatedAt
      description: Matching rules for the whole workspace. A post they reject is never billed.
  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.