880 lines
26 KiB
YAML
880 lines
26 KiB
YAML
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
|
|
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
|
|
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
|
|
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'
|
|
/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.
|
|
type: string
|
|
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_explorer_url:
|
|
description: Blockchain explorer base URL.
|
|
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: 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
|
|
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
|