openapi: 3.1.0
info:
  title: Bluesky Social Actor Profiles Chat Moderation API
  description: "The Bluesky Social API provides programmatic access to the Bluesky social network built on the AT Protocol. \n\nThis API enables developers to:\n- Manage user profiles and preferences\n- Create, read, and interact with posts and feeds\n- Handle social graph operations (follows, blocks, mutes)\n- Process notifications and conversations\n- Moderate content and manage labels\n- Synchronize repository data\n\nAuthentication is handled via Bearer tokens. Public endpoints can be accessed directly at https://public.api.bsky.app, while authenticated requests should be made to the user's Personal Data Server (PDS).\n\nFor more information, visit the [Bluesky API Documentation](https://docs.bsky.app)."
  version: 1.0.0
  contact:
    name: Bluesky Support
    url: https://bsky.app
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://bsky.social/xrpc
  description: Bluesky Social PDS
- url: https://public.api.bsky.app/xrpc
  description: Public Bluesky AppView API (unauthenticated endpoints)
tags:
- name: Chat Moderation
  description: Operations for moderating chat content.
paths:
  /xrpc/chat.bsky.moderation.getActorMetadata:
    get:
      operationId: chatModerationGetActorMetadata
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Chat Moderation
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: actor
        in: query
        required: true
        schema:
          type: string
          format: did
        example: did:plc:example123abc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - day
                - month
                - all
                properties:
                  day:
                    $ref: '#/components/schemas/ChatBskyModerationGetActorMetadataMetadata'
                  month:
                    $ref: '#/components/schemas/ChatBskyModerationGetActorMetadataMetadata'
                  all:
                    $ref: '#/components/schemas/ChatBskyModerationGetActorMetadataMetadata'
              examples:
                ChatModerationGetActorMetadataResponse200Example:
                  $ref: '#/components/examples/ChatModerationGetActorMetadataResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/chat.bsky.moderation.getMessageContext:
    get:
      operationId: chatModerationGetMessageContext
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Chat Moderation
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      parameters:
      - name: convoId
        in: query
        description: 'Conversation that the message is from. NOTE: this field will eventually be required.'
        required: false
        schema:
          type: string
          description: 'Conversation that the message is from. NOTE: this field will eventually be required.'
        example: example-convoId
      - name: messageId
        in: query
        required: true
        schema:
          type: string
        example: example-messageId
      - name: before
        in: query
        required: false
        schema:
          type: integer
          default: 5
        example: 5
      - name: after
        in: query
        required: false
        schema:
          type: integer
          default: 5
        example: 5
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - messages
                properties:
                  messages:
                    type: array
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/ChatBskyConvoDefsMessageView'
                      - $ref: '#/components/schemas/ChatBskyConvoDefsDeletedMessageView'
              examples:
                ChatModerationGetMessageContextResponse200Example:
                  $ref: '#/components/examples/ChatModerationGetMessageContextResponse200Example'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
  /xrpc/chat.bsky.moderation.updateActorAccess:
    post:
      operationId: chatModerationUpdateActorAccess
      summary: Bluesky Operation
      description: '*This endpoint is part of the Bluesky Chat (DMs) APIs. Requests usually require authentication, are directed to the user''s PDS intance, and proxied to the single central chat service by setting the appropriate service DID (`did:web:api.bsky.chat`) in the service proxying header.*


        *To learn more about calling atproto API endpoints like this one, see the [API Hosts and Auth](/docs/advanced-guides/api-directory) guide.*'
      tags:
      - Chat Moderation
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: ''
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - actor
              - allowAccess
              properties:
                actor:
                  type: string
                  format: did
                allowAccess:
                  type: boolean
                ref:
                  type: string
            examples:
              ChatModerationUpdateActorAccessRequestExample:
                $ref: '#/components/examples/ChatModerationUpdateActorAccessRequestExample'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - InvalidRequest
                    - ExpiredToken
                    - InvalidToken
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    const: AuthMissing
                  message:
                    type: string
components:
  schemas:
    AppBskyFeedDefsBlockedAuthor:
      type: object
      required:
      - did
      properties:
        did:
          type: string
          format: did
        viewer:
          $ref: '#/components/schemas/AppBskyActorDefsViewerState'
    AppBskyGraphDefsListViewBasic:
      type: object
      required:
      - uri
      - cid
      - name
      - purpose
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        name:
          type: string
          minLength: 1
          maxLength: 64
        purpose:
          $ref: '#/components/schemas/AppBskyGraphDefsListPurpose'
        avatar:
          type: string
          format: uri
        listItemCount:
          type: integer
          minimum: 0
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        viewer:
          $ref: '#/components/schemas/AppBskyGraphDefsListViewerState'
        indexedAt:
          type: string
          format: date-time
    ChatBskyModerationGetActorMetadataMetadata:
      type: object
      required:
      - messagesSent
      - messagesReceived
      - convos
      - convosStarted
      properties:
        messagesSent:
          type: integer
        messagesReceived:
          type: integer
        convos:
          type: integer
        convosStarted:
          type: integer
    ComAtprotoLabelDefsLabel:
      type: object
      description: Metadata tag on an atproto resource (eg, repo or record).
      required:
      - src
      - uri
      - val
      - cts
      properties:
        ver:
          type: integer
        src:
          type: string
          description: DID of the actor who created this label.
          format: did
        uri:
          type: string
          description: AT URI of the record, repository (account), or other resource that this label applies to.
          format: uri
        cid:
          type: string
          description: Optionally, CID specifying the specific version of 'uri' resource this label applies to.
          format: cid
        val:
          type: string
          description: The short string name of the value or type of this label.
          maxLength: 128
        neg:
          type: boolean
          description: If true, this is a negation label, overwriting a previous label.
        cts:
          type: string
          description: Timestamp when this label was created.
          format: date-time
        exp:
          type: string
          description: Timestamp at which this label expires (no longer applies).
          format: date-time
        sig:
          type: string
          format: byte
          description: Signature of dag-cbor encoded label.
    AppBskyEmbedImagesView:
      type: object
      required:
      - images
      properties:
        images:
          type: array
          items:
            $ref: '#/components/schemas/AppBskyEmbedImagesViewImage'
          maxItems: 4
    AppBskyRichtextFacetLink:
      type: object
      description: Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.
      required:
      - uri
      properties:
        uri:
          type: string
          format: uri
    AppBskyActorDefsProfileView:
      type: object
      required:
      - did
      - handle
      properties:
        did:
          type: string
          format: did
        handle:
          type: string
          format: handle
        displayName:
          type: string
          maxLength: 640
        description:
          type: string
          maxLength: 2560
        avatar:
          type: string
          format: uri
        associated:
          $ref: '#/components/schemas/AppBskyActorDefsProfileAssociated'
        indexedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        viewer:
          $ref: '#/components/schemas/AppBskyActorDefsViewerState'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
    AppBskyFeedDefsGeneratorViewerState:
      type: object
      properties:
        like:
          type: string
          format: at-uri
    AppBskyRichtextFacetMention:
      type: object
      description: Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.
      required:
      - did
      properties:
        did:
          type: string
          format: did
    AppBskyActorDefsProfileAssociatedChat:
      type: object
      required:
      - allowIncoming
      properties:
        allowIncoming:
          type: string
          enum:
          - all
          - none
          - following
    AppBskyEmbedRecordView:
      type: object
      required:
      - record
      properties:
        record:
          oneOf:
          - $ref: '#/components/schemas/AppBskyEmbedRecordViewRecord'
          - $ref: '#/components/schemas/AppBskyEmbedRecordViewNotFound'
          - $ref: '#/components/schemas/AppBskyEmbedRecordViewBlocked'
          - $ref: '#/components/schemas/AppBskyEmbedRecordViewDetached'
          - $ref: '#/components/schemas/AppBskyFeedDefsGeneratorView'
          - $ref: '#/components/schemas/AppBskyGraphDefsListView'
          - $ref: '#/components/schemas/AppBskyLabelerDefsLabelerView'
          - $ref: '#/components/schemas/AppBskyGraphDefsStarterPackViewBasic'
    ChatBskyConvoDefsMessageView:
      type: object
      required:
      - id
      - rev
      - text
      - sender
      - sentAt
      properties:
        id:
          type: string
        rev:
          type: string
        text:
          type: string
          maxLength: 10000
        facets:
          type: array
          items:
            $ref: '#/components/schemas/AppBskyRichtextFacet'
        embed:
          oneOf:
          - $ref: '#/components/schemas/AppBskyEmbedRecordView'
        sender:
          $ref: '#/components/schemas/ChatBskyConvoDefsMessageViewSender'
        sentAt:
          type: string
          format: date-time
    AppBskyActorDefsViewerState:
      type: object
      description: Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests.
      properties:
        muted:
          type: boolean
        mutedByList:
          $ref: '#/components/schemas/AppBskyGraphDefsListViewBasic'
        blockedBy:
          type: boolean
        blocking:
          type: string
          format: at-uri
        blockingByList:
          $ref: '#/components/schemas/AppBskyGraphDefsListViewBasic'
        following:
          type: string
          format: at-uri
        followedBy:
          type: string
          format: at-uri
        knownFollowers:
          $ref: '#/components/schemas/AppBskyActorDefsKnownFollowers'
    AppBskyActorDefsProfileAssociated:
      type: object
      properties:
        lists:
          type: integer
        feedgens:
          type: integer
        starterPacks:
          type: integer
        labeler:
          type: boolean
        chat:
          $ref: '#/components/schemas/AppBskyActorDefsProfileAssociatedChat'
    AppBskyEmbedExternalViewExternal:
      type: object
      required:
      - uri
      - title
      - description
      properties:
        uri:
          type: string
          format: uri
        title:
          type: string
        description:
          type: string
        thumb:
          type: string
          format: uri
    AppBskyEmbedVideoView:
      type: object
      required:
      - cid
      - playlist
      properties:
        cid:
          type: string
          format: cid
        playlist:
          type: string
          format: uri
        thumbnail:
          type: string
          format: uri
        alt:
          type: string
          maxLength: 10000
        aspectRatio:
          $ref: '#/components/schemas/AppBskyEmbedDefsAspectRatio'
    AppBskyActorDefsKnownFollowers:
      type: object
      description: The subject's followers whom you also follow
      required:
      - count
      - followers
      properties:
        count:
          type: integer
        followers:
          type: array
          items:
            $ref: '#/components/schemas/AppBskyActorDefsProfileViewBasic'
          maxItems: 5
    AppBskyGraphDefsListView:
      type: object
      required:
      - uri
      - cid
      - creator
      - name
      - purpose
      - indexedAt
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        creator:
          $ref: '#/components/schemas/AppBskyActorDefsProfileView'
        name:
          type: string
          minLength: 1
          maxLength: 64
        purpose:
          $ref: '#/components/schemas/AppBskyGraphDefsListPurpose'
        description:
          type: string
          maxLength: 3000
        descriptionFacets:
          type: array
          items:
            $ref: '#/components/schemas/AppBskyRichtextFacet'
        avatar:
          type: string
          format: uri
        listItemCount:
          type: integer
          minimum: 0
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        viewer:
          $ref: '#/components/schemas/AppBskyGraphDefsListViewerState'
        indexedAt:
          type: string
          format: date-time
    AppBskyActorDefsProfileViewBasic:
      type: object
      required:
      - did
      - handle
      properties:
        did:
          type: string
          format: did
        handle:
          type: string
          format: handle
        displayName:
          type: string
          maxLength: 640
        avatar:
          type: string
          format: uri
        associated:
          $ref: '#/components/schemas/AppBskyActorDefsProfileAssociated'
        viewer:
          $ref: '#/components/schemas/AppBskyActorDefsViewerState'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        createdAt:
          type: string
          format: date-time
    AppBskyGraphDefsListPurpose:
      oneOf:
      - $ref: '#/components/schemas/AppBskyGraphDefsModlist'
      - $ref: '#/components/schemas/AppBskyGraphDefsCuratelist'
      - $ref: '#/components/schemas/AppBskyGraphDefsReferencelist'
    AppBskyLabelerDefsLabelerView:
      type: object
      required:
      - uri
      - cid
      - creator
      - indexedAt
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        creator:
          $ref: '#/components/schemas/AppBskyActorDefsProfileView'
        likeCount:
          type: integer
          minimum: 0
        viewer:
          $ref: '#/components/schemas/AppBskyLabelerDefsLabelerViewerState'
        indexedAt:
          type: string
          format: date-time
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
    ChatBskyConvoDefsDeletedMessageView:
      type: object
      required:
      - id
      - rev
      - sender
      - sentAt
      properties:
        id:
          type: string
        rev:
          type: string
        sender:
          $ref: '#/components/schemas/ChatBskyConvoDefsMessageViewSender'
        sentAt:
          type: string
          format: date-time
    AppBskyRichtextFacetByteSlice:
      type: object
      description: 'Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.'
      required:
      - byteStart
      - byteEnd
      properties:
        byteStart:
          type: integer
          minimum: 0
        byteEnd:
          type: integer
          minimum: 0
    AppBskyRichtextFacet:
      type: object
      description: Annotation of a sub-string within rich text.
      required:
      - index
      - features
      properties:
        index:
          $ref: '#/components/schemas/AppBskyRichtextFacetByteSlice'
        features:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/AppBskyRichtextFacetMention'
            - $ref: '#/components/schemas/AppBskyRichtextFacetLink'
            - $ref: '#/components/schemas/AppBskyRichtextFacetTag'
    AppBskyLabelerDefsLabelerViewerState:
      type: object
      properties:
        like:
          type: string
          format: at-uri
    AppBskyEmbedRecordViewRecord:
      type: object
      required:
      - uri
      - cid
      - author
      - value
      - indexedAt
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        author:
          $ref: '#/components/schemas/AppBskyActorDefsProfileViewBasic'
        value: {}
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        replyCount:
          type: integer
        repostCount:
          type: integer
        likeCount:
          type: integer
        quoteCount:
          type: integer
        embeds:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/AppBskyEmbedImagesView'
            - $ref: '#/components/schemas/AppBskyEmbedVideoView'
            - $ref: '#/components/schemas/AppBskyEmbedExternalView'
            - $ref: '#/components/schemas/AppBskyEmbedRecordView'
            - $ref: '#/components/schemas/AppBskyEmbedRecordWithMediaView'
        indexedAt:
          type: string
          format: date-time
    AppBskyEmbedImagesViewImage:
      type: object
      required:
      - thumb
      - fullsize
      - alt
      properties:
        thumb:
          type: string
          description: Fully-qualified URL where a thumbnail of the image can be fetched. For example, CDN location provided by the App View.
          format: uri
        fullsize:
          type: string
          description: Fully-qualified URL where a large version of the image can be fetched. May or may not be the exact original blob. For example, CDN location provided by the App View.
          format: uri
        alt:
          type: string
          description: Alt text description of the image, for accessibility.
        aspectRatio:
          $ref: '#/components/schemas/AppBskyEmbedDefsAspectRatio'
    AppBskyEmbedRecordViewDetached:
      type: object
      required:
      - uri
      - detached
      properties:
        uri:
          type: string
          format: at-uri
        detached:
          type: boolean
          default: true
    ChatBskyConvoDefsMessageViewSender:
      type: object
      required:
      - did
      properties:
        did:
          type: string
          format: did
    AppBskyGraphDefsCuratelist:
      type: string
      format: token
      description: A list of actors used for curation purposes such as list feeds or interaction gating.
    AppBskyEmbedDefsAspectRatio:
      type: object
      description: width:height represents an aspect ratio. It may be approximate, and may not correspond to absolute dimensions in any given unit.
      required:
      - width
      - height
      properties:
        width:
          type: integer
          minimum: 1
        height:
          type: integer
          minimum: 1
    AppBskyEmbedRecordWithMediaView:
      type: object
      required:
      - record
      - media
      properties:
        record:
          $ref: '#/components/schemas/AppBskyEmbedRecordView'
        media:
          oneOf:
          - $ref: '#/components/schemas/AppBskyEmbedImagesView'
          - $ref: '#/components/schemas/AppBskyEmbedVideoView'
          - $ref: '#/components/schemas/AppBskyEmbedExternalView'
    AppBskyGraphDefsReferencelist:
      type: string
      format: token
      description: A list of actors used for only for reference purposes such as within a starter pack.
    AppBskyFeedDefsGeneratorView:
      type: object
      required:
      - uri
      - cid
      - did
      - creator
      - displayName
      - indexedAt
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        did:
          type: string
          format: did
        creator:
          $ref: '#/components/schemas/AppBskyActorDefsProfileView'
        displayName:
          type: string
        description:
          type: string
          maxLength: 3000
        descriptionFacets:
          type: array
          items:
            $ref: '#/components/schemas/AppBskyRichtextFacet'
        avatar:
          type: string
          format: uri
        likeCount:
          type: integer
          minimum: 0
        acceptsInteractions:
          type: boolean
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        viewer:
          $ref: '#/components/schemas/AppBskyFeedDefsGeneratorViewerState'
        indexedAt:
          type: string
          format: date-time
    AppBskyGraphDefsModlist:
      type: string
      format: token
      description: A list of actors to apply an aggregate moderation action (mute/block) on.
    AppBskyRichtextFacetTag:
      type: object
      description: Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').
      required:
      - tag
      properties:
        tag:
          type: string
          maxLength: 640
    AppBskyGraphDefsListViewerState:
      type: object
      properties:
        muted:
          type: boolean
        blocked:
          type: string
          format: at-uri
    AppBskyEmbedRecordViewNotFound:
      type: object
      required:
      - uri
      - notFound
      properties:
        uri:
          type: string
          format: at-uri
        notFound:
          type: boolean
          default: true
    AppBskyEmbedExternalView:
      type: object
      required:
      - external
      properties:
        external:
          $ref: '#/components/schemas/AppBskyEmbedExternalViewExternal'
    AppBskyGraphDefsStarterPackViewBasic:
      type: object
      required:
      - uri
      - cid
      - record
      - creator
      - indexedAt
      properties:
        uri:
          type: string
          format: at-uri
        cid:
          type: string
          format: cid
        record: {}
        creator:
          $ref: '#/components/schemas/AppBskyActorDefsProfileViewBasic'
        listItemCount:
          type: integer
          minimum: 0
        joinedWeekCount:
          type: integer
          minimum: 0
        joinedAllTimeCount:
          type: integer
          minimum: 0
        labels:
          type: array
          items:
            $ref: '#/components/schemas/ComAtprotoLabelDefsLabel'
        indexedAt:
          type: string
          format: date-time
    AppBskyEmbedRecordViewBlocked:
      type: object
      required:
      - uri
      - blocked
      - author
      properties:
        uri:
          type: string
          format: at-uri
        blocked:
          type: boolean
          default: true
        author:
          $ref: '#/components/schemas/AppBskyFeedDefsBlockedAuthor'
  examples:
    ChatModerationGetMessageContextResponse200Example:
      summary: Successful response for chatModerationGetMessageContext
      value:
        messages:
        - id: example-id
          rev: example-rev
          text: Example text content
          sender:
            did: {}
          sentAt: '2024-01-15T12:00:00.000Z'
          facets: []
          embed: {}
    ChatModerationUpdateActorAccessRequestExample:
      summary: Example request for chatModerationUpdateActorAccess
      value:
        actor: did:plc:example123abc
        allowAccess: true
        ref: example-ref
    ChatModerationGetActorMetadataResponse200Example:
      summary: Successful response for chatModerationGetActorMetadata
      value:
        day:
          messagesSent: 50
          messagesReceived: 50
          convos: 50
          convosStarted: 50
        month:
          messagesSent: 50
          messagesReceived: 50
          convos: 50
          convosStarted: 50
        all:
          messagesSent: 50
          messagesReceived: 50
          convos: 50
          convosStarted: 50
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer