parsimony/docs/openapi.yaml
tgiachi 1ba42316fd feat: wire REST API into the daemon and document it
- Add api.listen config; token comes from PARSIMONY_API_TOKEN
- Disable the API when the token is not set
- Add OpenAPI description and README usage
2026-11-09 14:57:57 +01:00

151 lines
4.1 KiB
YAML

openapi: 3.0.3
info:
title: Parsimony admin API
version: 1.0.0
servers:
- url: /api/v1
security:
- bearer: []
components:
securitySchemes:
bearer:
type: http
scheme: bearer
schemas:
List:
type: object
properties:
id: {type: integer}
name: {type: string}
domain: {type: string}
title: {type: string}
address: {type: string}
Member:
type: object
properties:
address: {type: string}
display_name: {type: string}
Error:
type: object
properties:
error: {type: string}
responses:
Error:
description: Error
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
paths:
/health:
get:
security: []
summary: Liveness check
responses:
'200': {description: OK}
/lists:
get:
summary: List all lists
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/List'}}
post:
summary: Create a list
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, domain]
properties:
name: {type: string}
domain: {type: string}
title: {type: string}
responses:
'201':
description: Created
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'400': {$ref: '#/components/responses/Error'}
'409': {$ref: '#/components/responses/Error'}
/lists/{id}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: Get a list
responses:
'200':
description: OK
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'404': {$ref: '#/components/responses/Error'}
patch:
summary: Update the list title
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [title]
properties:
title: {type: string}
responses:
'200':
description: OK
content:
application/json:
schema: {$ref: '#/components/schemas/List'}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
delete:
summary: Delete a list and its members
responses:
'204': {description: Deleted}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/members:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: List members
responses:
'200':
description: OK
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/Member'}}
'404': {$ref: '#/components/responses/Error'}
post:
summary: Add a member (idempotent)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [address]
properties:
address: {type: string}
display_name: {type: string}
responses:
'201':
description: Created
content:
application/json:
schema: {$ref: '#/components/schemas/Member'}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/members/{address}:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
- {name: address, in: path, required: true, schema: {type: string}}
delete:
summary: Remove a member
responses:
'204': {description: Removed}
'404': {$ref: '#/components/responses/Error'}