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.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - password
                    - ethereum
                username:
                  description: User name (required if grant type is "password").
                  type: string
                wallet_address:
                  description: Ethereum wallet address (required if grant type is "ethereum").
                  type: string
                  example: null
                password:
                  type: string
              required:
                - grant_type
                - password
      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.
                  type: string
                wallet_address:
                  description: Ethereum wallet address.
                  type: string
                  example: '0xd8da6bf...'
                invite_code:
                  description: Invite code
                  type: string
                  example: 9b288bfa7dc75fff53e98aa4d76e77d5
              required:
                - username
                - password
      responses:
        201:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        400:
          description: Invalid user data
  /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'
      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.
                  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.
                  type: string
                  enum:
                    - public
                    - private
                    - direct
                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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        404:
          description: Post does not exist or is not public
  /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:
                type: object
                properties:
                  v:
                    type: integer
                    format: int64
                    example: 27
                  r:
                    type: string
                    example: '6f61670e67bf72...'
                  s:
                    type: string
                    example: '6a5cb313907cd3...'
        403:
          description: Post does not belong to user, is not public or not saved to IPFS, or user's wallet address is not known
        404:
          description: Post not found
        418:
          description: Ethereum 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
      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/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'

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
        wallet_address:
          description: Ethereum wallet address.
          type: string
          example: '0xd8da6bf...'
    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: The version of Mitra server.
          type: string
        registrations:
          description: Whether registrations are enabled.
          type: boolean
        login_message:
          description: Login message for signer.
          type: string
        blockchain_explorer_url:
          description: Blockchain explorer base URL.
          type: string
        blockchain_contract_name:
          description: Blockchain contract name.
          type: string
        blockchain_contract_address:
          description: Blockchain contract address.
          type: string
        ipfs_gateway_url:
          description: IPFS gateway URL.
          type: string
    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
          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: The account id.
          type: string
          format: uuid
        following:
          description: Are you following this user?
          type: boolean
        followed_by:
          description: Are you followed by this user?
          type: boolean
        requested:
          description: Do you have a pending follow request for this user?
          type: boolean
    Status:
      type: object
      properties:
        id:
          type: string
          format: uuid
        content:
          description: HTML-encoded post content.
          type: string
        visibility:
          description: Visibility of this post.
          type: string
          enum:
            - public
            - private
            - direct
        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.