diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/swagger.yaml | 101 | ||||
| -rw-r--r-- | docs/configuration/instance.md | 26 |
2 files changed, 124 insertions, 3 deletions
diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml index fa1bd7499..38562c8ad 100644 --- a/docs/api/swagger.yaml +++ b/docs/api/swagger.yaml @@ -784,6 +784,35 @@ definitions: type: object x-go-name: Card x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model + domain: + description: Domain represents a remote domain + properties: + domain: + description: The hostname of the domain. + example: example.org + type: string + x-go-name: Domain + public_comment: + description: If the domain is blocked, what's the publicly-stated reason for + the block. + example: they smell + type: string + x-go-name: PublicComment + silenced_at: + description: Time at which this domain was silenced. Key will not be present + on open domains. + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SilencedAt + suspended_at: + description: Time at which this domain was suspended. Key will not be present + on open domains. + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SuspendedAt + type: object + x-go-name: Domain + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model domainBlock: description: DomainBlock represents a block on one domain properties: @@ -798,7 +827,7 @@ definitions: type: string x-go-name: CreatedBy domain: - description: The hostname of the blocked domain. + description: The hostname of the domain. example: example.org type: string x-go-name: Domain @@ -822,16 +851,28 @@ definitions: type: string x-go-name: PrivateComment public_comment: - description: Public comment for this block, visible if domain blocks are served - publicly. + description: If the domain is blocked, what's the publicly-stated reason for + the block. example: they smell type: string x-go-name: PublicComment + silenced_at: + description: Time at which this domain was silenced. Key will not be present + on open domains. + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SilencedAt subscription_id: description: The ID of the subscription that created/caused this domain block. example: 01FBW25TF5J67JW3HFHZCSD23K type: string x-go-name: SubscriptionID + suspended_at: + description: Time at which this domain was suspended. Key will not be present + on open domains. + example: "2021-07-30T09:20:25+00:00" + type: string + x-go-name: SuspendedAt type: object x-go-name: DomainBlock x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model @@ -3038,6 +3079,60 @@ paths: for the instance. tags: - instance + /api/v1/instance/peers: + get: + operationId: instancePeersGet + parameters: + - description: |- + Comma-separated list of filters to apply to results. Recognized values are: + 'open' -- include peers that are not suspended or silenced + 'suspended' -- include peers that have been suspended. + If filter is 'open', only instances that haven't been suspended or silenced will be returned. + If filter is 'suspended', only suspended instances will be shown. + If filter is 'open,suspended', then all known instances will be returned. + If filter is an empty string or not set, then 'open' will be assumed as the default. + in: query + name: filter + type: string + produces: + - application/json + responses: + "200": + description: |- + If no filter parameter is provided, or filter is empty, then a legacy, + Mastodon-API compatible response will be returned. This will consist of + just a 'flat' array of strings like `["example.com", "example.org"]`. + + If a filter parameter is provided, then an array of objects with at least + a `domain` key set on each object will be returned. + + Domains that are silenced or suspended will also have a key + 'suspended_at' or 'silenced_at' that contains an iso8601 date string. + If one of these keys is not present on the domain object, it is open. + Suspended instances may in some cases be obfuscated, which means they + will have some letters replaced by '*' to make it more difficult for + bad actors to target instances with harassment. + + Whether a flat response or a more detailed response is returned, domains + will be sorted alphabetically by hostname. + schema: + items: + $ref: '#/definitions/domain' + type: array + "400": + description: bad request + "401": + description: unauthorized + "403": + description: forbidden + "404": + description: not found + "406": + description: not acceptable + "500": + description: internal server error + tags: + - instance /api/v1/media: post: consumes: diff --git a/docs/configuration/instance.md b/docs/configuration/instance.md new file mode 100644 index 000000000..2451b9903 --- /dev/null +++ b/docs/configuration/instance.md @@ -0,0 +1,26 @@ +# Instance + +## Settings + +```yaml +########################### +##### INSTANCE CONFIG ##### +########################### + +# Config pertaining to instance federation settings, pages to hide/expose, etc. + +# Bool. Allow unauthenticated users to make queries to /api/v1/instance/peers?filter=open in order +# to see a list of instances that this instance 'peers' with. Even if set to 'false', then authenticated +# users (members of the instance) will still be able to query the endpoint. +# Options: [true, false] +# Default: false +instance-expose-peers: false + +# Bool. Allow unauthenticated users to make queries to /api/v1/instance/peers?filter=suspended in order +# to see a list of instances that this instance blocks/suspends. This will also allow unauthenticated +# users to see the list through the web UI. Even if set to 'false', then authenticated users (members +# of the instance) will still be able to query the endpoint. +# Options: [true, false] +# Default: false +instance-expose-suspended: false +``` |