admin API · Marula PSA docs

API reference

15 operations in admin. Raw spec: openapi.json.

GET/api/v1/reply-snippets

GET /api/v1/reply-snippets — the org's snippet library with the search-in-composer predicate applied (`board_id` offer filter + `q` case-insensitive substring over name and body).

Parameters

Name	In	Type	Required	Description
`board_id`	query	string	No	Offer-board filter: only snippets scoped to every board or this board (the composer passes the ticket's board).
`q`	query	string	No	Search-in-composer predicate: case-insensitive substring over the snippet's name and body.

Responses

Status	Description
`200`
`403`	requires tickets:view or admin:view

Security: bearer

POST/api/v1/reply-snippets

POST /api/v1/reply-snippets — add a snippet to the library.

Request body

CreateReplySnippetRequest

Responses

Status	Description
`200`
`403`	requires admin:create
`422`	validation failure (name/body, or out-of-vocabulary variable)

Security: bearer

GET/api/v1/reply-snippets/{id}

GET /api/v1/reply-snippets/{id} — fetch one snippet (cross-lane fix, Wave 34 lane 4: the fork-on-edit flow reads the origin after forking; the route was missing so reads 405'd).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`403`	requires tickets:view or admin:view
`404`

Security: bearer

PATCH/api/v1/reply-snippets/{id}

PATCH /api/v1/reply-snippets/{id} — edit a snippet in place (the library is org-owned data; fork-on-edit applies when orgs want a divergent copy, via the fork endpoint).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

UpdateReplySnippetRequest

Responses

Status	Description
`200`
`403`	requires admin:edit
`404`	snippet not visible in scope
`409`	version gate rejected the write (IF3)
`422`	validation failure

Security: bearer

DELETE/api/v1/reply-snippets/{id}

DELETE /api/v1/reply-snippets/{id} — remove a snippet from the library.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`403`	requires admin:delete
`404`	snippet not visible in scope

Security: bearer

POST/api/v1/reply-snippets/{id}/fork

POST /api/v1/reply-snippets/{id}/fork — duplicate a snippet into a new editable copy (templates fork-on-edit provenance pattern). The origin is untouched; the copy records `forked_from`.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

ForkReplySnippetRequest

Responses

Status	Description
`200`
`403`	requires admin:create
`404`	snippet not visible in scope
`422`	validation failure

Security: bearer

POST/api/v1/reply-snippets/{id}/render

POST /api/v1/reply-snippets/{id}/render — resolve the snippet's variable tokens against a real ticket context and return the rendered body (the composer inserts the RENDERED text; the portal reply renders the result). Out-of-vocabulary placeholders are typed 400s.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

RenderReplySnippetRequest

Responses

Status	Description
`200`
`400`	out-of-vocabulary or malformed variable
`403`	requires tickets:view or admin:view
`404`	snippet or ticket not visible in scope

Security: bearer

GET/api/v1/templates

GET /api/templates — the org's templates (shipped defaults first, then org-owned rows), optionally filtered by kind.

Parameters

Name	In	Type	Required	Description
`kind`	query	string	No	filter to one template kind
`limit`	query	integer	No
`offset`	query	integer	No

Responses

Status	Description
`200`
`403`	requires admin:view

Security: bearer

POST/api/v1/templates

POST /api/templates — create an org-owned template (shipped defaults are seed data; fork them instead of copying by hand).

Request body

CreateTemplateRequest

Responses

Status	Description
`200`
`400`	validation failure (unknown kind, bad slug, out-of-vocabulary variable)
`403`	requires admin:create
`409`	slug taken or idempotency key reused

Security: bearer

GET/api/v1/templates/{id}

GET /api/templates/{id}

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`403`	requires admin:view
`404`	template not visible in scope

Security: bearer

PATCH/api/v1/templates/{id}

PATCH /api/templates/{id} — edit an org-owned template's content. Shipped defaults are immutable (typed 409 `template_immutable`): fork first, edit the fork.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

UpdateTemplateRequest

Responses

Status	Description
`200`
`404`	template not visible in scope
`409`	template immutable, version conflict, or idempotency key reused
`422`	validation failure

Security: bearer

DELETE/api/v1/templates/{id}

DELETE /api/templates/{id} — remove an org-owned template. Shipped defaults are immutable (typed 409 `template_immutable`).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Responses

Status	Description
`200`
`404`	template not visible in scope
`409`	template immutable or idempotency key reused

Security: bearer

POST/api/v1/templates/{id}/fork

POST /api/templates/{id}/fork — duplicate a template (typically a shipped default) into a mutable org-owned copy. The origin row is untouched.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

ForkTemplateRequest

Responses

Status	Description
`200`
`404`	template not visible in scope
`409`	slug taken or idempotency key reused
`422`	validation failure

Security: bearer

POST/api/v1/templates/{id}/render

POST /api/templates/{id}/render — resolve the template's typed variables against real entity context and return the rendered subject/body. Out-of-vocabulary placeholders are typed 400s, never silent empties (KB3).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

RenderTemplateRequest

Responses

Status	Description
`200`
`400`	out-of-vocabulary or malformed variable
`403`	requires admin:view
`404`	template or context entity not visible in scope

Security: bearer

POST/api/v1/templates/{id}/restore

POST /api/templates/{id}/restore — reset a shipped default's content to the canonical copy (KB4: presets stay canonical, orgs fork). Org-owned rows and forks are org-owned data and are never restorable.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

RestoreTemplateRequest

Responses

Status	Description
`200`
`404`	template not visible in scope, or not a shipped default
`409`	version conflict or idempotency key reused

Security: bearer