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. parameters: - name: did in: query description: Identifier (DID) required: true schema: type: string example: 'did:pkh:eip155:1:0xb9c5714089478a327f09197987f16f9e5d936e8a' 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"}' 400: description: Invalid request parameters post: summary: Submit identity proof. requestBody: content: application/json: schema: type: object properties: did: description: Identifier (DID) type: string example: 'did:pkh:eip155:1:0xb9c5714089478a327f09197987f16f9e5d936e8a' signature: description: Signature value. type: string example: '3312dacd...' responses: 200: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Account' 400: description: Invalid proof data. /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/search: get: summary: Search for matching profiles by username. parameters: - name: q in: query description: What to search for required: true schema: type: string - name: limit in: query description: Maximum number of results. Defaults to 40. required: false schema: type: number responses: 200: description: Successful operation content: application/json: schema: description: Profile list type: array items: $ref: '#/components/schemas/Account' /api/v1/accounts/search_did: get: summary: Search profile by DID parameters: - name: did in: query description: Decentralized identifier (DID) required: true schema: type: string responses: 200: description: Successful operation content: application/json: schema: description: Profile list type: array items: $ref: '#/components/schemas/Account' 400: description: Invalid DID /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: exclude_replies in: query description: Exclude replies from results. required: false schema: type: boolean default: true - 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' headers: Link: description: Link to the next page schema: type: string example: '; rel="next"' 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' headers: Link: description: Link to the next page schema: type: string example: '; rel="next"' 404: description: Profile not found /api/v1/accounts/{account_id}/subscribers: get: summary: Subscriptions to the given actor. parameters: - $ref: '#/components/parameters/account_id' - name: max_id in: query description: Return results with subscription 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: Subscription list type: array items: $ref: '#/components/schemas/Subscription' 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/subscriptions/authorize: get: summary: Get authorization for setting up Ethereum subscription. security: - tokenAuth: [] parameters: - name: price in: query description: Subscription price required: true schema: type: number 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/subscriptions/options: get: summary: Get list of subscription options security: - tokenAuth: [] responses: 200: description: Successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/SubscriptionOption' post: summary: Enable subscriptions or update subscription settings security: - tokenAuth: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionOption' responses: 200: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Account' 400: description: User hasn't enabled subscriptions 403: description: User's wallet address is not known or not verified 418: description: Blockchain integration is not enabled /api/v1/subscriptions/find: get: summary: Find subscription by sender and recipient parameters: - name: sender_id in: query description: Sender ID. required: true schema: type: string format: uuid - name: recipient_id in: query description: Recipient ID. required: true schema: type: string format: uuid responses: 200: description: Successful operation content: application/json: schema: type: object properties: id: description: Subscription ID. type: number example: 1 expires_at: description: The date when subscription expires. type: string format: dateTime 404: description: Subscription not found /api/v1/subscriptions/invoices: post: summary: Create invoice requestBody: content: application/json: schema: type: object properties: sender_id: description: Sender ID. type: string format: uuid recipient_id: description: Recipient ID. type: string format: uuid amount: description: Requested payment amount (in atomic units). type: integer example: 100000000 responses: 200: description: Invoice created. content: application/json: schema: $ref: '#/components/schemas/Invoice' 400: description: Invalid request. 404: description: Sender or recipient not found. 418: description: Blockchain integration is not enabled. /api/v1/subscriptions/invoices/{invoice_id}: get: summary: View information about an invoice. parameters: - name: invoice_id in: path description: Invoice ID required: true schema: type: string format: uuid responses: 200: description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Invoice' 404: description: Invoice not found /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' hashtags: type: array items: $ref: '#/components/schemas/Tag' 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' payment_options: description: Payment options. type: array items: type: object properties: type: description: Payment type. type: string enum: - link - ethereum-subscription - monero-subscription name: description: Link name (only for link type). type: string nullable: true href: description: Link URL (only for link type). type: string nullable: true price: description: Subscription price (only for ethereum-subscription and monero-subscription types). type: number nullable: true example: null fields: description: Additional metadata attached to a profile as name-value pairs. type: array items: $ref: '#/components/schemas/Field' followers_count: description: The reported followers of this profile. type: number following_count: description: The reported follows of this profile. type: number subscribers_count: description: The reported subscribers of this profile. type: number 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 blockchains: description: Information about blockchain integrations. type: array items: type: object properties: chain_id: description: CAIP-2 chain ID. type: string example: 'eip155:1' chain_metadata: description: Additional information about blockchain type: object nullable: true contract_address: description: Blockchain contract address. type: string nullable: true features: description: Blockchain features. type: object properties: minter: description: Minter feature flag. type: boolean example: true subscriptions: description: Subscriptions feature flag. type: boolean example: true ipfs_gateway_url: description: IPFS gateway URL. type: string nullable: true Invoice: type: object properties: id: description: Invoice ID. type: string format: uuid sender_id: description: The profile ID of the sender. type: string format: uuid recipient_id: description: The profile ID of the recipient. type: string format: uuid payment_address: description: Payment address. type: string amount: description: Requested payment amount (in atomic units). type: integer example: 100000000 status: description: Invoice status. type: string enum: - open - paid - forwarded - timeout 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 - subscription_expiration 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 uri: description: URI of the post used for federation. type: string 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 account: description: The profile that authored this post. $ref: '#/components/schemas/Account' 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. type: array items: $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...' reblog: description: The post being reposted. type: object quote: description: The post being quoted. type: object Subscription: type: object properties: id: description: Subscription ID. type: number sender: $ref: '#/components/schemas/Account' sender_address: description: Sender address. type: string nullable: true example: '0xd8da6bf...' expires_at: description: The date when subscription expires. type: string format: dateTime SubscriptionOption: type: object properties: type: description: Subscription type type: string enum: - ethereum - monero price: description: Subscription price (only for Monero) type: number payout_address: description: Payout address (only for Monero) type: string required: - type 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