Table of contents

Put ADR Documents from Repository

If you already have ADR documents in your Repository, you can put them directly to Pistacy.io using our API. Such documents are not editable, but are visible in your project. Following page describes how to put ADR documents using API.

Put document

Document you are about to put has few requirements:

Must be written using Markdown format
Must has unique identifier - mostly the filename

Basic request to API states as follows. Notice that you need to replace

{DOCUMENT-ID} - Document ID, can be filename.
{PROJECT-ID} - Project ID which document shoud be placed to, inside the Organization.
{API-KEY} - Organization API Key.

curl --location --request PUT 'https://app.pistacy.io/org-api/v1/adrs/external/{DOCUMENT-ID}'
--header 'Accept: application/json, text/plain, */*'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {API-KEY}'
--header 'X-Project-ID: {PROJECT-ID}'
--data '{
    "content": "Lorem ispum dolor sit amet."
}'

Updating document

System will create ADR if document with given ID does not exist, or will update the document, if exists. No matter which operation you want to perform - just put the document using this endpoint with the same ID.

Document title

By default, filename stands as a title of document. If you want to change title of the document, just place Heading 1 in the Markdown document. System will notice this title and update the Document title

# Document title
Lorem ispum dolor sit amet.

Document metadata

By default, documents you put are in default status (draft), date and (rejection, cancellation, etc.) reason. You can define a Metadata in every document to store those details inside your repository. Everytime when document will be updated, metadata will be read and updated within document.

Currently supported metadatas:

status - Must be one of the ADR statuses: draft, accepted, implemented, archived, superseded, deprecated, obsolete, rejected.
date - Document creation date. Format: Y-m-d or Y-m-d H:i:s.
reason - Last status change reason. Why it was rejected, retired etc.

Metadata are stored at the beginning of the document, using YAML format. Every field is optional, but recommended to store within documents. As you can see below, metadata is a stored stored between three dashes. After metadata you can place the document content.

---
status: implemented
date: 2025-03-01
---
# Document title
Lorem ispum dolor sit amet.

Unsupported statuses

You have to provide only supported statuses, because those are mapped to our State Machine. If you have own or different ones, please update them first, to fit supported ones.