API Quick Start

API quick start

This guide creates a harmless draft through the document REST API. It does not send signing invitations. For sending and field placement, see Agreement and Workflow API.

Before you begin

Ask your deployment operator for the API base URL, approved token provisioning method, and an account or client with the required scopes. The API may be hosted separately from the website. Examples use https://api.example.com as an illustrative origin; it is not a graphsign.ink service.

Use HTTPS and send tokens in Authorization: Bearer …. Keep tokens in a secret manager or local environment, not in source files, URLs, screenshots, or public logs. Do not mint your own tokens or assume a standard OAuth token endpoint exists in this application.

The following examples use a POSIX shell and curl. Set API_BASE_URL and ACCESS_TOKEN securely in your environment before running them. Windows users can use an equivalent API client or adapt shell syntax; avoid pasting credentials into shared command history.

1. List documents

curl --fail-with-body "$API_BASE_URL/api/v1/documents?limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Required scope: documents:read. A successful response contains data and pagination.

2. Create a Markdown draft

Create a local document.json file containing this synthetic content:

{
  "name": "Example service agreement",
  "content": "# Example agreement\n\nThis is demonstration content only.",
  "contentEncoding": "utf-8",
  "mimeType": "text/markdown",
  "description": "Documentation sample",
  "tags": ["demo"],
  "metadata": {"folder": "Examples"}
}

curl --fail-with-body -X POST "$API_BASE_URL/api/v1/documents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-create-agreement-001" \
  --data-binary @document.json

Required scope: documents:create. Creation normally returns 201, a document object, and a Location header. Save the returned id. The response contains summary metadata, not the entire source document or signed PDF.

Use a fresh idempotency key for each new logical creation. If retrying the same request, keep the same key, path, and exact payload. A stored successful replay returns 200 and replay headers; a changed payload using the same key or an in-progress duplicate can return 409.

3. Retrieve or update the draft

Replace DOCUMENT_ID with the returned identifier:

curl --fail-with-body "$API_BASE_URL/api/v1/documents/DOCUMENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

To change selected draft properties, create update.json:

{"description":"Updated demonstration description","tags":["demo","reviewed"]}

curl --fail-with-body -X PATCH "$API_BASE_URL/api/v1/documents/DOCUMENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @update.json

Required scope: documents:update. PUT and PATCH only update draft documents. Do not rely on expectedRevision for concurrency protection in these handlers.

4. Continue in the application

Open the new draft in Agreements, inspect the content, configure fields and recipients, and follow your review and sending process. A document CRUD request does not itself configure a complete signing workflow.

Next steps

• REST API Reference: methods, payloads, pagination, and errors.
• Agreement and Workflow API: recipients, fields, review, and send.
• Webhooks and REST API Integration: callback management and receiver verification.
• Feature Availability: implemented behavior and deployment requirements.