OpenAPI reference

This reference is generated from api/openapi.json (OpenAPI 3.1.0, API version 1.0.0). Read the foundation guide for session handling, permissions, and examples.

Download the OpenAPI specification. The running service also publishes it at /api/openapi.json. API paths below are relative to your SongCollect service origin.

Versioned, language-independent SongCollect interface. Browser sessions use an HttpOnly cookie. Every mutation requires the configured APP_ORIGIN header; native clients must retain the cookie and send that origin too. Native token authentication and cross-origin browser hosting are future work. Repeated Idempotency-Key requests replay the committed response; PUT requires the quoted revision ETag in If-Match. Public routes expose active song heads only.

Authentication🔗

developmentSession: apiKey, sent in cookie as songcollect.
session: apiKey, sent in cookie as __Host-songcollect.

Security alternatives listed on an endpoint mean either cookie is accepted. Endpoints marked public do not require a session.

Endpoints🔗

GET `/api/health/live`🔗

Operation: live.

Authentication: public.

Responses

Status	Description	Body
200		`application/json`: Health
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/health/ready`🔗

Operation: ready.

Authentication: public.

Responses

Status	Description	Body
200		`application/json`: Health
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody
503		`application/json`: Health

GET `/api/v1/churches`🔗

Operation: churches.

Authentication: session or developmentSession.

Responses

Status	Description	Body
200		`application/json`: Churches
401		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/churches/{churchId}/songs`🔗

Operation: list.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`q`	query	No	`string`	maxLength: `200`
`offset`	query	No	`integer` (int64)	minimum: `0`; maximum: `100000`

Responses

Status	Description	Body
200		`application/json`: Catalogue
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

POST `/api/v1/churches/{churchId}/songs`🔗

Operation: create.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type
`churchId`	path	Yes	`string` (uuid)
`Origin`	header	Yes	`string`
`Idempotency-Key`	header	Yes	`string` (uuid)

Request body (required)

application/json: MetadataInput

Responses

Status	Description	Body	Headers
201		`application/json`: SongResponse	`ETag`: `string`; `Location`: `string`
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
403		`application/json`: ErrorBody
404		`application/json`: ErrorBody
409		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/churches/{churchId}/songs/{songId}`🔗

Operation: get.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)

Responses

Status	Description	Body	Headers
200		`application/json`: SongResponse	`ETag`: `string` — Quoted current revision
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

PUT `/api/v1/churches/{churchId}/songs/{songId}`🔗

Operation: update.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)
`Origin`	header	Yes	`string`
`Idempotency-Key`	header	Yes	`string` (uuid)
`If-Match`	header	Yes	`string`	Strong ETag from the base revision, e.g. "1"

Request body (required)

application/json: MetadataInput

Responses

Status	Description	Body	Headers
200		`application/json`: SongResponse	`ETag`: `string`
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
403		`application/json`: ErrorBody
404		`application/json`: ErrorBody
409		`application/json`: ErrorBody
412		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
428		`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/churches/{churchId}/songs/{songId}/lyrics`🔗

Operation: list_lyrics.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)

Responses

Status	Description	Body
200		`application/json`: LyricVersions
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

POST `/api/v1/churches/{churchId}/songs/{songId}/lyrics`🔗

Operation: create_lyrics.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)
`Origin`	header	Yes	`string`
`Idempotency-Key`	header	Yes	`string` (uuid)

Request body (required)

application/json: NewLyrics

Responses

Status	Description	Body	Headers
201		`application/json`: LyricVersionResponse	`ETag`: `string`; `Location`: `string`
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
403		`application/json`: ErrorBody
404		`application/json`: ErrorBody
409		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}`🔗

Operation: get_lyrics.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)
`lyricVersionId`	path	Yes	`string` (uuid)

Responses

Status	Description	Body	Headers
200		`application/json`: LyricVersionResponse	`ETag`: `string` — Quoted current lyric version
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

PUT `/api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}`🔗

Operation: update_lyrics.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)
`lyricVersionId`	path	Yes	`string` (uuid)
`Origin`	header	Yes	`string`
`Idempotency-Key`	header	Yes	`string` (uuid)
`If-Match`	header	Yes	`string`	Strong ETag of the base lyric version, e.g. "1"

Request body (required)

application/json: LyricsDocument

Responses

Status	Description	Body	Headers
200		`application/json`: LyricVersionResponse	`ETag`: `string`
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
403		`application/json`: ErrorBody
404		`application/json`: ErrorBody
409		`application/json`: ErrorBody
412	Stale version; currentLyrics holds the latest revision	`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
428		`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}/revisions`🔗

Operation: lyric_revisions.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)
`lyricVersionId`	path	Yes	`string` (uuid)
`beforeVersion`	query	No	`integer` (int32)	minimum: `1`; maximum: `2147483647`

Responses

Status	Description	Body
200		`application/json`: LyricRevisions
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/churches/{churchId}/songs/{songId}/revisions`🔗

Operation: revisions.

Authentication: session or developmentSession.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)
`beforeVersion`	query	No	`integer` (int32)	minimum: `1`; maximum: `2147483647`

Responses

Status	Description	Body
200		`application/json`: Revisions
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/public/churches/{churchId}/songs`🔗

Operation: public_list.

Authentication: public.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`q`	query	No	`string`	maxLength: `200`
`offset`	query	No	`integer` (int64)	minimum: `0`; maximum: `100000`

Responses

Status	Description	Body
200		`application/json`: Catalogue
400		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/public/churches/{churchId}/songs/{songId}`🔗

Operation: public_get.

Authentication: public.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)

Responses

Status	Description	Body	Headers
200		`application/json`: SongResponse	`ETag`: `string`
400		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

GET `/api/v1/public/churches/{churchId}/songs/{songId}/lyrics`🔗

Operation: public_lyrics.

Authentication: public.

Parameters

Name	Location	Required	Type	Constraints / description
`churchId`	path	Yes	`string` (uuid)
`songId`	path	Yes	`string` (uuid)

Responses

Status	Description	Body
200		`application/json`: LyricVersions
400		`application/json`: ErrorBody
404		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

POST `/api/v1/session`🔗

Operation: login.

Authentication: public.

Parameters

Name	Location	Required	Type	Constraints / description
`Origin`	header	Yes	`string`	Configured APP_ORIGIN

Request body (required)

application/json: Credentials

Responses

Status	Description	Body
204	Signed in; HttpOnly session cookie set	No body
400		`application/json`: ErrorBody
401		`application/json`: ErrorBody
403		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429		`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

DELETE `/api/v1/session`🔗

Operation: logout.

Authentication: public.

Parameters

Name	Location	Required	Type	Constraints / description
`Origin`	header	Yes	`string`

Responses

Status	Description	Body
204	Session revoked and cookie cleared	No body
403		`application/json`: ErrorBody
413	Request body exceeds 32 KiB	`application/json`: ErrorBody
429	Rate limit exceeded	`application/json`: ErrorBody
500	Unexpected server error	`application/json`: ErrorBody

Schemas🔗

Catalogue🔗

Property	Required	Type	Constraints / description
`church`	Yes	Church
`hasMore`	Yes	`boolean`
`lyricMatches`	Yes	array of LyricMatch	Lyric versions of the listed songs whose text matched the search.
`songs`	Yes	array of Song

JSON schema

{
  "type": "object",
  "required": [
    "church",
    "songs",
    "hasMore",
    "lyricMatches"
  ],
  "properties": {
    "church": {
      "$ref": "#/components/schemas/Church"
    },
    "hasMore": {
      "type": "boolean"
    },
    "lyricMatches": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricMatch"
      },
      "description": "Lyric versions of the listed songs whose text matched the search."
    },
    "songs": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Song"
      }
    }
  }
}

Church🔗

Property	Required	Type
`id`	Yes	`string` (uuid)
`name`	Yes	`string`
`role`	No	Role or `null`
`timeZone`	Yes	`string`

JSON schema

{
  "type": "object",
  "required": [
    "id",
    "name",
    "timeZone"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "role": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/Role"
        },
        {
          "type": "null"
        }
      ]
    },
    "timeZone": {
      "type": "string"
    }
  }
}

Churches🔗

Property	Required	Type	Constraints / description
`churches`	Yes	array of Church

JSON schema

{
  "type": "object",
  "required": [
    "churches"
  ],
  "properties": {
    "churches": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Church"
      }
    }
  }
}

Credentials🔗

Property	Required	Type	Constraints / description
`email`	Yes	`string` (email)	maxLength: `254`
`password`	Yes	`string`	minLength: `1`; maxLength: `256`

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "required": [
    "email",
    "password"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "password": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1
    }
  },
  "additionalProperties": false
}

ErrorBody🔗

Property	Required	Type
`current`	No	Song or `null`
`currentLyrics`	No	LyricVersion or `null`
`error`	Yes	`string`

JSON schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "current": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/Song"
        },
        {
          "type": "null"
        }
      ]
    },
    "currentLyrics": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/LyricVersion",
          "description": "The current lyric version when a lyric save is rejected as stale."
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "type": "string"
    }
  }
}

Health🔗

Property	Required	Type	Constraints / description
`status`	Yes	`string`

JSON schema

{
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string"
    }
  }
}

LyricLine🔗

Property	Required	Type	Constraints / description
`id`	Yes	`string` (uuid)	Stable line identity. Keep it when editing the text; generate a new UUID for an added line.
`text`	Yes	`string`	maxLength: `200`

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "required": [
    "id",
    "text"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Stable line identity. Keep it when editing the text; generate a new\nUUID for an added line."
    },
    "text": {
      "type": "string",
      "maxLength": 200
    }
  },
  "additionalProperties": false
}

LyricMatch🔗

Property	Required	Type
`label`	Yes	`string`
`language`	Yes	`string`
`lyricVersionId`	Yes	`string` (uuid)
`songId`	Yes	`string` (uuid)

JSON schema

{
  "type": "object",
  "required": [
    "songId",
    "lyricVersionId",
    "language",
    "label"
  ],
  "properties": {
    "label": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "lyricVersionId": {
      "type": "string",
      "format": "uuid"
    },
    "songId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

LyricRevision🔗

Property	Required	Type
`createdAt`	Yes	`string` (date-time)
`id`	Yes	`string` (uuid)
`label`	Yes	`string`
`sections`	Yes	array of LyricSection
`sequence`	Yes	array of `string` (uuid)
`version`	Yes	`integer` (int32)

JSON schema

{
  "type": "object",
  "required": [
    "id",
    "version",
    "label",
    "sections",
    "sequence",
    "createdAt"
  ],
  "properties": {
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "label": {
      "type": "string"
    },
    "sections": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricSection"
      }
    },
    "sequence": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      }
    },
    "version": {
      "type": "integer",
      "format": "int32"
    }
  }
}

LyricRevisions🔗

Property	Required	Type	Constraints / description
`hasMore`	Yes	`boolean`
`revisions`	Yes	array of LyricRevision	maxItems: `50`

JSON schema

{
  "type": "object",
  "required": [
    "revisions",
    "hasMore"
  ],
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "revisions": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricRevision"
      },
      "maxItems": 50
    }
  }
}

LyricSection🔗

Property	Required	Type	Constraints / description
`id`	Yes	`string` (uuid)	Stable section identity referenced by singing sequences.
`lines`	Yes	array of LyricLine	minItems: `1`; maxItems: `200`
`name`	Yes	`string`	minLength: `1`; maxLength: `80`; Display name such as "Verse 1" or "Chorus"; unique within the document.

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "required": [
    "id",
    "name",
    "lines"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Stable section identity referenced by singing sequences."
    },
    "lines": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricLine"
      },
      "maxItems": 200,
      "minItems": 1
    },
    "name": {
      "type": "string",
      "description": "Display name such as \"Verse 1\" or \"Chorus\"; unique within the document.",
      "maxLength": 80,
      "minLength": 1
    }
  },
  "additionalProperties": false
}

LyricVersion🔗

Property	Required	Type	Constraints / description
`id`	Yes	`string` (uuid)
`label`	Yes	`string`
`language`	Yes	`string`
`revisionId`	Yes	`string` (uuid)
`sections`	Yes	array of LyricSection
`sequence`	Yes	array of `string` (uuid)
`songId`	Yes	`string` (uuid)
`updatedAt`	Yes	`string` (date-time)
`version`	Yes	`integer` (int32)	Increments with each saved revision; send it quoted in If-Match.

JSON schema

{
  "type": "object",
  "required": [
    "id",
    "songId",
    "language",
    "version",
    "revisionId",
    "label",
    "sections",
    "sequence",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "label": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "revisionId": {
      "type": "string",
      "format": "uuid"
    },
    "sections": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricSection"
      }
    },
    "sequence": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      }
    },
    "songId": {
      "type": "string",
      "format": "uuid"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "version": {
      "type": "integer",
      "format": "int32",
      "description": "Increments with each saved revision; send it quoted in If-Match."
    }
  }
}

LyricVersionResponse🔗

Property	Required	Type	Constraints / description
`lyrics`	Yes	LyricVersion

JSON schema

{
  "type": "object",
  "required": [
    "lyrics"
  ],
  "properties": {
    "lyrics": {
      "$ref": "#/components/schemas/LyricVersion"
    }
  }
}

LyricVersions🔗

Property	Required	Type	Constraints / description
`lyrics`	Yes	array of LyricVersion	maxItems: `20`; Lyric versions of the song, ordered by language and creation.

JSON schema

{
  "type": "object",
  "required": [
    "lyrics"
  ],
  "properties": {
    "lyrics": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricVersion"
      },
      "description": "Lyric versions of the song, ordered by language and creation.",
      "maxItems": 20
    }
  }
}

LyricsDocument🔗

The revisioned content of a lyric version.

Property	Required	Type	Constraints / description
`label`	Yes	`string`	maxLength: `80`; Edition label such as "Original" or "Simplified".
`sections`	Yes	array of LyricSection	minItems: `1`; maxItems: `40`
`sequence`	Yes	array of `string` (uuid)	maxItems: `100`; Default singing sequence as section IDs. Sections may repeat. Empty means the section order is sung.

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "description": "The revisioned content of a lyric version.",
  "required": [
    "label",
    "sections",
    "sequence"
  ],
  "properties": {
    "label": {
      "type": "string",
      "description": "Edition label such as \"Original\" or \"Simplified\".",
      "maxLength": 80
    },
    "sections": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricSection"
      },
      "maxItems": 40,
      "minItems": 1
    },
    "sequence": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Default singing sequence as section IDs. Sections may repeat. Empty\nmeans the section order is sung.",
      "maxItems": 100
    }
  },
  "additionalProperties": false
}

Metadata🔗

Property	Required	Type	Constraints / description
`alternateTitles`	Yes	array of `string`	maxItems: `20`
`authors`	Yes	array of `string`	maxItems: `30`
`copyright`	Yes	`string`	maxLength: `1000`
`songbooks`	Yes	array of Songbook	maxItems: `30`
`themes`	Yes	array of `string`	maxItems: `30`
`title`	Yes	`string`	minLength: `1`; maxLength: `200`

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "required": [
    "title",
    "alternateTitles",
    "authors",
    "copyright",
    "themes",
    "songbooks"
  ],
  "properties": {
    "alternateTitles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20
    },
    "authors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 30
    },
    "copyright": {
      "type": "string",
      "maxLength": 1000
    },
    "songbooks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Songbook"
      },
      "maxItems": 30
    },
    "themes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 30
    },
    "title": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
    }
  },
  "additionalProperties": false
}

MetadataInput🔗

Property	Required	Type	Constraints / description
`alternateTitles`	No	array of `string`	maxItems: `20`
`authors`	No	array of `string`	maxItems: `30`
`copyright`	No	`string`	maxLength: `1000`
`songbooks`	No	array of Songbook	maxItems: `30`
`themes`	No	array of `string`	maxItems: `30`
`title`	Yes	`string`	minLength: `1`; maxLength: `200`

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "alternateTitles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20
    },
    "authors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 30
    },
    "copyright": {
      "type": "string",
      "maxLength": 1000
    },
    "songbooks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Songbook"
      },
      "maxItems": 30
    },
    "themes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 30
    },
    "title": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
    }
  },
  "additionalProperties": false
}

NewLyrics🔗

Property	Required	Type	Constraints / description
`label`	Yes	`string`	maxLength: `80`
`language`	Yes	`string`	minLength: `2`; maxLength: `35`; BCP 47 language tag, fixed for the lifetime of the lyric version.
`sections`	Yes	array of LyricSection	minItems: `1`; maxItems: `40`
`sequence`	Yes	array of `string` (uuid)	maxItems: `100`

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "required": [
    "language",
    "label",
    "sections",
    "sequence"
  ],
  "properties": {
    "label": {
      "type": "string",
      "maxLength": 80
    },
    "language": {
      "type": "string",
      "description": "BCP 47 language tag, fixed for the lifetime of the lyric version.",
      "example": "de",
      "maxLength": 35,
      "minLength": 2
    },
    "sections": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/LyricSection"
      },
      "maxItems": 40,
      "minItems": 1
    },
    "sequence": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "maxItems": 100
    }
  },
  "additionalProperties": false
}

Revision🔗

Property	Required	Type
`createdAt`	Yes	`string` (date-time)
`id`	Yes	`string` (uuid)
`metadata`	Yes	Metadata
`version`	Yes	`integer` (int32)

JSON schema

{
  "type": "object",
  "required": [
    "id",
    "version",
    "metadata",
    "createdAt"
  ],
  "properties": {
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "metadata": {
      "$ref": "#/components/schemas/Metadata"
    },
    "version": {
      "type": "integer",
      "format": "int32"
    }
  }
}

Revisions🔗

Property	Required	Type	Constraints / description
`hasMore`	Yes	`boolean`
`revisions`	Yes	array of Revision	maxItems: `50`

JSON schema

{
  "type": "object",
  "required": [
    "revisions",
    "hasMore"
  ],
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "revisions": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Revision"
      },
      "maxItems": 50
    }
  }
}

Role🔗

Type: string. allowed: "Administrator", "Editor", "Viewer"

JSON schema

{
  "type": "string",
  "enum": [
    "Administrator",
    "Editor",
    "Viewer"
  ]
}

Song🔗

Property	Required	Type
`id`	Yes	`string` (uuid)
`metadata`	Yes	Metadata
`revisionId`	Yes	`string` (uuid)
`updatedAt`	Yes	`string` (date-time)
`version`	Yes	`integer` (int32)

JSON schema

{
  "type": "object",
  "required": [
    "id",
    "version",
    "revisionId",
    "metadata",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "metadata": {
      "$ref": "#/components/schemas/Metadata"
    },
    "revisionId": {
      "type": "string",
      "format": "uuid"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "version": {
      "type": "integer",
      "format": "int32"
    }
  }
}

SongResponse🔗

Property	Required	Type	Constraints / description
`song`	Yes	Song

JSON schema

{
  "type": "object",
  "required": [
    "song"
  ],
  "properties": {
    "song": {
      "$ref": "#/components/schemas/Song"
    }
  }
}

Songbook🔗

Property	Required	Type	Constraints / description
`book`	Yes	`string`	minLength: `1`; maxLength: `200`
`number`	Yes	`string`	minLength: `1`; maxLength: `30`

Unknown properties are rejected.

JSON schema

{
  "type": "object",
  "required": [
    "book",
    "number"
  ],
  "properties": {
    "book": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
    },
    "number": {
      "type": "string",
      "maxLength": 30,
      "minLength": 1
    }
  },
  "additionalProperties": false
}

Authentication🔗

Endpoints🔗

GET /api/health/live🔗

GET /api/health/ready🔗

GET /api/v1/churches🔗

GET /api/v1/churches/{churchId}/songs🔗

POST /api/v1/churches/{churchId}/songs🔗

GET /api/v1/churches/{churchId}/songs/{songId}🔗

PUT /api/v1/churches/{churchId}/songs/{songId}🔗

GET /api/v1/churches/{churchId}/songs/{songId}/lyrics🔗

POST /api/v1/churches/{churchId}/songs/{songId}/lyrics🔗

GET /api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}🔗

PUT /api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}🔗

GET /api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}/revisions🔗

GET /api/v1/churches/{churchId}/songs/{songId}/revisions🔗

GET /api/v1/public/churches/{churchId}/songs🔗

GET /api/v1/public/churches/{churchId}/songs/{songId}🔗

GET /api/v1/public/churches/{churchId}/songs/{songId}/lyrics🔗

POST /api/v1/session🔗

DELETE /api/v1/session🔗

Schemas🔗

Catalogue🔗

Church🔗

Churches🔗

Credentials🔗

ErrorBody🔗

Health🔗

LyricLine🔗

LyricMatch🔗

LyricRevision🔗

LyricRevisions🔗

LyricSection🔗

LyricVersion🔗

LyricVersionResponse🔗

LyricVersions🔗

LyricsDocument🔗

Metadata🔗

MetadataInput🔗

NewLyrics🔗

Revision🔗

Revisions🔗

Role🔗

Song🔗

SongResponse🔗

Songbook🔗

GET `/api/health/live`🔗

GET `/api/health/ready`🔗

GET `/api/v1/churches`🔗

GET `/api/v1/churches/{churchId}/songs`🔗

POST `/api/v1/churches/{churchId}/songs`🔗

GET `/api/v1/churches/{churchId}/songs/{songId}`🔗

PUT `/api/v1/churches/{churchId}/songs/{songId}`🔗

GET `/api/v1/churches/{churchId}/songs/{songId}/lyrics`🔗

POST `/api/v1/churches/{churchId}/songs/{songId}/lyrics`🔗

GET `/api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}`🔗

PUT `/api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}`🔗

GET `/api/v1/churches/{churchId}/songs/{songId}/lyrics/{lyricVersionId}/revisions`🔗

GET `/api/v1/churches/{churchId}/songs/{songId}/revisions`🔗

GET `/api/v1/public/churches/{churchId}/songs`🔗

GET `/api/v1/public/churches/{churchId}/songs/{songId}`🔗

GET `/api/v1/public/churches/{churchId}/songs/{songId}/lyrics`🔗

POST `/api/v1/session`🔗

DELETE `/api/v1/session`🔗