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.