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/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/accounts/{account_id}/statuses:
    get:
      summary: Statuses posted to the given account.
      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'
  /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}/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 or is not public or user's wallet address is not known
        404:
          description: Post not found
        418:
          description: Ethereum integration is not enabled
        422:
          description: Post is not saved to IPFS
  /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:
  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
        wallet_address:
          description: Ethereum wallet address.
          type: string
          example: '0xd8da6bf...'
    Status:
      type: object
      properties:
        id:
          type: string
          format: uuid
        content:
          description: HTML-encoded status content.
          type: string
        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.