openapi: 3.0.1
info:
  title: Mitra API
  description: Mitra API spec
  version: 1.0.0

paths:
  /oauth/token:
    post:
      summary: Returns an access token, to be used during API calls that are not public.
      description: EIP-4361 auth doesn't require blockchain integration.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - password
                    - eip4361
                  example: eip4361
                username:
                  description: User name (required if grant type is "password").
                  type: string
                message:
                  description: EIP-4361 message (required if grant type is "eip4361").
                  type: string
                  example: "example.com wants you to sign in with your Ethereum account:"
                signature:
                  description: EIP-4361 signature (required if grant type is "eip4361").
                  type: string
                  example: 0x905...
                password:
                  description: Password (required if grant type is "password").
                  type: string
                  example: null
              required:
                - grant_type
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                    example: Bearer
                  scope:
                    type: string
                    example: read write follow
                  created_at:
                    type: integer
                    example: 1639747526
        400:
          description: Invalid token request
  /api/v1/accounts:
    post:
      summary: Creates a user and profile records.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  description: The desired username for the account.
                  type: string
                password:
                  description: The password to be used for login. Either password or EIP-4361 message must be provided.
                  type: string
                  example: null
                message:
                  description: EIP-4361 message
                  type: string
                  example: "example.com wants you to sign in with your Ethereum account:"
                signature:
                  description: EIP-4361 signature (required if message is present)
                  type: string
                  example: 0x905...
                invite_code:
                  description: Invite code
                  type: string
                  example: 9b288bfa7dc75fff53e98aa4d76e77d5
              required:
                - username
      responses:
        201:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        400:
          description: Invalid user data
  /api/v1/accounts/identity_proof:
    get:
      summary: Get unsigned data for identity proof.
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  claim:
                    description: Identity claim serialized as compact JSON.
                    type: string
                    example: '{"id":"https://example.com/users/1","ownerOf":"did:pkh:eip155:1:0xb9c5714089478a327f09197987f16f9e5d936e8a"}'
        403:
          description: User's wallet address is not known
    post:
      summary: Submit identity proof.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  description: Signature value.
                  type: string
                  example: '3312dacd...'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        400:
          description: Invalid signature.
        403:
          description: User's wallet address is not known
  /api/v1/accounts/authorize_subscription:
    get:
      summary: Get authorization for setting up paid subscription.
      responses:
        200:
          description: Signature created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Signature'
        403:
          description: User's wallet address is not known or not verified
        418:
          description: Blockchain integration is not enabled
  /api/v1/accounts/relationships:
    get:
      summary: Find out whether a given actor is followed, blocked, muted, etc.
      parameters:
        - name: 'id[]'
          in: query
          description: Actor IDs to check
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Relationship list
                type: array
                items:
                  $ref: '#/components/schemas/Relationship'
  /api/v1/accounts/{account_id}:
    get:
      summary: View information about a profile.
      parameters:
        - $ref: '#/components/parameters/account_id'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        404:
          description: Profile not found
  /api/v1/accounts/{account_id}/statuses:
    get:
      summary: Posts created by the given actor.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - name: max_id
          in: query
          description: Return results older than this ID.
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 20
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Post list
                type: array
                items:
                  $ref: '#/components/schemas/Status'
        404:
          description: Profile not found
  /api/v1/accounts/{account_id}/followers:
    get:
      summary: Actors which follow the given actor.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - name: max_id
          in: query
          description: Return results with relationship ID older than this value.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 40
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Profile list
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        404:
          description: Profile not found
  /api/v1/accounts/{account_id}/following:
    get:
      summary: Actors which the given actor is following.
      parameters:
        - $ref: '#/components/parameters/account_id'
        - name: max_id
          in: query
          description: Return results with relationship ID older than this value.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 40
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Profile list
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        404:
          description: Profile not found
  /api/v1/accounts/{account_id}/follow:
    post:
      summary: Follow the given actor.
      security:
        - tokenAuth: []
      parameters:
        - $ref: '#/components/parameters/account_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reblogs:
                  description: Receive this actor's reposts in home timeline?
                  type: boolean
                  default: true
                replies:
                  description: Receive this actor's replies in home timeline?
                  type: boolean
                  default: true
      responses:
        200:
          description: Successfully followed, or actor was already followed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Relationship'
        404:
          description: Profile not found
  /api/v1/accounts/{account_id}/unfollow:
    post:
      summary: Unfollow the given actor.
      security:
        - tokenAuth: []
      parameters:
        - $ref: '#/components/parameters/account_id'
      responses:
        200:
          description: Successfully unfollowed, or actor was already not followed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Relationship'
        404:
          description: Profile not found
  /api/v1/directory:
    get:
      summary: List accounts visible in the directory.
      parameters:
        - name: offset
          in: query
          description: How many accounts to skip before returning results.
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: How many accounts to load.
          required: false
          schema:
            type: integer
            default: 40
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Profile list
                type: array
                items:
                  $ref: '#/components/schemas/Account'
  /api/v1/instance:
    get:
      summary: Information about the instance.
      security: []
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
  /api/v1/notifications:
    get:
      summary: Notifications concerning the user.
      parameters:
        - name: max_id
          in: query
          description: Return results older than this ID.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 20
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Notification list
                type: array
                items:
                  $ref: '#/components/schemas/Notification'
  /api/v1/statuses:
    post:
      summary: Create new post.
      security:
        - tokenAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  description: |
                    Text content of the post.
                    Allowed HTML tags: a, br, pre, code.
                  type: string
                'media_ids[]':
                  description: Array of Attachment ids to be attached as media.
                  type: array
                  items:
                    type: string
                    format: uuid
                in_reply_to_id:
                  description: ID of the post being replied to, if post is a reply.
                  type: string
                  format: uuid
                visibility:
                  description: Visibility of the post.
                  $ref: '#/components/schemas/Visibility'
                mentions:
                  description: Array of profile IDs to be mentioned
                  type: array
                  items:
                    type: string
                    format: uuid
              required:
                - status
      responses:
        201:
          description: Post created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        400:
          description: Invalid post data
  /api/v1/statuses/{status_id}:
    delete:
      summary: Delete post
      parameters:
        - $ref: '#/components/parameters/status_id'
      responses:
        204:
          description: Successful operation
          content: {}
        403:
          description: Post does not belong to user
        404:
          description: Post not found
  /api/v1/statuses/{status_id}/favourite:
    post:
      summary: Add post to your favourites list
      parameters:
        - $ref: '#/components/parameters/status_id'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        404:
          description: Post does not exist or is not public
  /api/v1/statuses/{status_id}/reblog:
    post:
      summary: Repost a post
      parameters:
        - $ref: '#/components/parameters/status_id'
      responses:
        200:
          description: Successful operation. Returns repost info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        404:
          description: Post does not exist or is not public
  /api/v1/statuses/{status_id}/unreblog:
    post:
      summary: Undo repost
      parameters:
        - $ref: '#/components/parameters/status_id'
      responses:
        200:
          description: Post no longer resposted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        404:
          description: Post does not exist or no repost exists
  /api/v1/statuses/{status_id}/make_permanent:
    post:
      summary: Save post to IPFS
      parameters:
        - $ref: '#/components/parameters/status_id'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        403:
          description: Post does not belong to user or is not public
        404:
          description: Post not found
        418:
          description: IPFS integration is not enabled
        422:
          description: Post already saved to IPFS
  /api/v1/statuses/{status_id}/signature:
    get:
      summary: Sign post data with instance key
      parameters:
        - $ref: '#/components/parameters/status_id'
      responses:
        200:
          description: Signature created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Signature'
        403:
          description: Post does not belong to user, is not public or not saved to IPFS, or user's wallet address is not known or not verified
        404:
          description: Post not found
        418:
          description: Blockchain integration is not enabled
  /api/v1/statuses/{status_id}/token_minted:
    post:
      summary: Register transaction that mints a token
      parameters:
        - $ref: '#/components/parameters/status_id'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                transaction_id:
                  type: string
                  description: Transaction ID
                  example: '581186ab56765aed64a3e73172872a6454c604c6b4e08a8ed03eabad94e74d64'
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        403:
          description: Post does not belong to user or is not public
        404:
          description: Post not found
        422:
          description: Transaction already registered
  /api/v1/timelines/public:
    get:
      summary: View local public posts.
      parameters:
        - name: max_id
          in: query
          description: Return results older than this ID.
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 20
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Post list
                type: array
                items:
                  $ref: '#/components/schemas/Status'
  /api/v1/timelines/tag/{hashtag}:
    get:
      summary: View public posts containing the given hashtag
      parameters:
        - name: hashtag
          in: path
          description: Hashtag name
          required: true
          schema:
            type: string
        - name: max_id
          in: query
          description: Return results older than this ID.
          required: false
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 20
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Post list
                type: array
                items:
                  $ref: '#/components/schemas/Status'
  /api/v2/search:
    get:
      summary: Search for profiles or posts
      parameters:
        - name: q
          in: query
          description: The search query
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                description: Search results
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/Status'

components:
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
  parameters:
    account_id:
      name: account_id
      in: path
      description: Profile ID
      required: true
      schema:
        type: string
        format: uuid
    status_id:
      name: status_id
      in: path
      description: Post ID
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    Account:
      type: object
      properties:
        id:
          description: The account id.
          type: string
          format: uuid
        username:
          description: The username of the actor, not including domain.
          type: string
          example: user
        acct:
          description: The Webfinger account URI. Equal to username for local actors, or username@domain for remote actors.
          type: string
          example: user@example.com
        url:
          description: The location of the user's profile page.
          type: string
          example: https://example.com/@user
        identity_proofs:
          description: Identity proofs.
          type: array
          items:
            $ref: '#/components/schemas/Field'
        fields:
          description: Additional metadata attached to a profile as name-value pairs.
          type: array
          items:
            $ref: '#/components/schemas/Field'
        wallet_address:
          description: Ethereum wallet address (visibile only to the current user).
          type: string
          nullable: true
          example: '0xd8da6bf...'
    Attachment:
      type: object
      properties:
        id:
          description: The ID of the attachment in the database.
          type: string
          format: uuid
        type:
          description: The type of the attachment.
          type: string
          enum:
            - unknown
            - image
            - video
        url:
          description: The location of the original full-size attachment.
          type: string
    Field:
      type: object
      properties:
        name:
          description: The key of a given field's key-value pair.
          type: string
        value:
          description: The value associated with the name key.
          type: string
        verified_at:
          description: Timestamp of when the server verified the field value.
          type: string
          format: dateTime
    Instance:
      type: object
      properties:
        uri:
          description: The host name of the instance.
          type: string
        title:
          description: The title of the website.
          type: string
        short_description:
          description: A short description defined by the admin.
          type: string
        description:
          description: Admin-defined description of the site.
          type: string
        version:
          description: Mastodon API compatibility version and the version of Mitra server.
          type: string
          example: '3.0.0 (compatible; Mitra 0.4.0)'
        registrations:
          description: Whether registrations are enabled.
          type: boolean
        login_message:
          description: Login message for signer.
          type: string
        post_character_limit:
          description: Post character limit.
          type: integer
          example: 5000
        blockchain_id:
          description: CAIP-2 chain ID.
          type: string
          nullable: true
          example: 'eip155:1'
        blockchain_explorer_url:
          description: Blockchain explorer base URL.
          type: string
          nullable: true
        blockchain_contract_address:
          description: Blockchain contract address.
          type: string
          nullable: true
        ipfs_gateway_url:
          description: IPFS gateway URL.
          type: string
          nullable: true
    Mention:
      type: object
      properties:
        id:
          description: The profile ID of the mentioned user.
          type: string
          format: uuid
        username:
          description: The username of the mentioned user.
          type: string
        acct:
          type: string
        url:
          description: The location of the mentioned user's profile.
          type: string
    Notification:
      type: object
      properties:
        id:
          description: The id of the notification in the database.
          type: string
        type:
          description: The type of event that resulted in the notification.
          type: string
          enum:
            - follow
            - follow_request
            - reply
            - favourite
            - mention
            - reblog
            - subscription
          example: reply
        created_at:
          description: The timestamp of the notification.
          type: string
          format: dateTime
        account:
          $ref: '#/components/schemas/Account'
        status:
          $ref: '#/components/schemas/Account'
    Relationship:
      type: object
      properties:
        id:
          description: Target profile id.
          type: string
          format: uuid
        following:
          description: Are you following this user?
          type: boolean
          default: false
        followed_by:
          description: Are you followed by this user?
          type: boolean
          default: false
        requested:
          description: Do you have a pending follow request for this user?
          type: boolean
          default: false
        subscription_to:
          description: Are you sending subscription payments to this user?
          type: boolean
          default: false
        subscription_from:
          description: Are you receiving subscription payments from this user?
          type: boolean
          default: false
        showing_reblogs:
          description: Are you receiving this user's reposts in your home timeline?
          type: boolean
          default: true
        showing_replies:
          description: Are you receiving this user's replies in your home timeline?
          type: boolean
          default: true
    Signature:
      type: object
      properties:
        v:
          type: integer
          format: int64
          example: 27
        r:
          type: string
          example: '6f61670e67bf72...'
        s:
          type: string
          example: '6a5cb313907cd3...'
    Status:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          description: The date when this post was created.
          type: string
          format: dateTime
        edited_at:
          description: The date when this post was edited.
          type: string
          format: dateTime
          nullable: true
        content:
          description: HTML-encoded post content.
          type: string
        visibility:
          description: Visibility of this post.
          $ref: '#/components/schemas/Visibility'
        media_attachments:
          description: Media that is attached to this post.
          $ref: '#/components/schemas/Attachment'
        mentions:
          description: Mentions of users within the post.
          type: array
          items:
            $ref: '#/components/schemas/Mention'
        tags:
          description: Hashtags used within the status content.
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        ipfs_cid:
          type: string
          nullable: true
          example: 'bafkr...'
        token_tx_id:
          type: string
          nullable: true
          example: '0x5fe80cdea7f...'
    Tag:
      type: object
      properties:
        name:
          description: 'The value of the hashtag after the # sign.'
          type: string
        url:
          description: A link to the hashtag on the instance.
    Visibility:
      type: string
      enum:
        - public
        - private
        - subscribers
        - direct