Public API documentation

Request a template-based document draft or a document review and have the results sent by email. No account or API key is required. Users can continue with amendments or answers by replying to Piwakawaka via email.

Raw AI drafting is not available. Select a supported template or review type from discovery.

Agent instructions

  1. Read GET /api/public/v1/discovery to find supported document types, company types, required context and current limits. For a review, collect the company type and applicable context answers before submitting; do not leave these for the recipient to answer by email.
  2. Supply the user's first_name and recipient email address for every draft or review, and obtain permission to send the documents there. Use their known first name or ask for it; do not invent one. Set recipient_authority_acknowledged: true only with permission. Missing or blank first name returns HTTP 422 before any work or email is scheduled.
  3. Send POST /api/public/v1/requests with a random 32–128 character Idempotency-Key header. Retain that key and the exact request, including ordered files.
  4. A 202 response means the request was accepted for processing, not that a document is finished. Tell the user to check their email for the first draft, review results or questions.
  5. If checking progress, poll the returned status_url no more often than once every ten seconds. Stop when processing and delivery reach a terminal status. provider_accepted does not prove inbox delivery.
  6. Further answers and amendments happen by replying to the email. The receipt provides status only, not document access. There are no API editing, download or resend operations.

Template-based drafting

Use a doc_type returned by discovery. Replace the example recipient with the address the user has authorised.

{
  "company_context": "startup_growth",
  "company_profile": {
    "entityName": "Example Limited"
  },
  "counterparty_profile": {
    "entityName": "Other Example Limited"
  },
  "first_name": "Alex",
  "instructions": "Prepare a mutual NDA for discussions about a software project. Leave unknown details clearly marked and ask me about them by email.",
  "options": {
    "doc_type": "nda"
  },
  "recipient_authority_acknowledged": true,
  "recipient_email": "recipient@example.test",
  "workflow": "standard_draft"
}
curl --fail-with-body "$BASE_URL/api/public/v1/requests" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @draft.json

Set BASE_URL to this site's origin. Generate one random idempotency key per new request, for example with python -c 'import secrets; print(secrets.token_urlsafe(32))'. Save the example JSON as draft.json.

Document review and uploads

Send multipart form data with a request JSON field and repeated files parts. target_files selects the zero-based indexes of the documents to review. Other uploaded files provide context and are not marked up.

Every review must include company_context: startup_growth for a startup/growing business, stable_service_provider for an established independent business, or corporate_group for a corporate group. Missing or invalid company type returns HTTP 422 before any work or email is scheduled.

Add free-text background, priorities or specific questions in options.review_context (up to 12,000 characters). Use options.additional_context for structured answers to the applicable additional_context_fields from discovery, and options.review_direction (buying or selling) when needed to clarify the client's role. Other uploaded files can provide further context without being marked up.

Set options.risk_rating and options.leverage_rating to low, medium or high to choose the review risk and negotiating leverage. Both are optional and can be supplied independently. If either is omitted, the normal document and company-context defaults apply to that rating.

{
  "company_context": "startup_growth",
  "company_profile": {
    "entityName": "Example Limited"
  },
  "first_name": "Alex",
  "instructions": "Review the attached agreement for Example Limited.",
  "options": {
    "leverage_rating": "medium",
    "review_context": "We are sharing information to evaluate a potential software project. Focus on confidentiality and practical obligations.",
    "risk_rating": "low"
  },
  "recipient_authority_acknowledged": true,
  "recipient_email": "recipient@example.test",
  "target_files": [
    0
  ],
  "workflow": "review"
}
curl --fail-with-body "$BASE_URL/api/public/v1/requests" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --form 'request=<review.json' \
  --form 'files=@agreement.docx'

Save the example JSON as review.json. Upload up to six DOCX, PDF or DOC files within the total size limit; select at most two review targets. Template drafting can also use multipart uploads for supporting context. Some templates require an underlying agreement.

For terms published on a public HTTPS page, use workflow: "review" and url: "https://example.org/terms". A URL counts as one source and one review target. Linked pages are not automatically included.

Provide company and counterparty details when known. An email address alone does not load a saved profile. Company type is required for review submission; supply all other known context up front to avoid clarification emails. If classification reveals an unanswered document-specific question, it may still need to be resolved by email.

Results and follow-up

Drafts arrive as Word documents with any remaining questions. Review results include the summary and appropriate reviewed copies. Reply directly to the delivery email to continue the request.

The receipt's status_url returns only processing and delivery status. Keep the receipt private. Receipts are retained for seven days by default.

Limits and errors

Default limits are three accepted requests per recipient per rolling 24 hours, ten per IP per rolling 24 hours, and three per IP per minute. Instructions must contain 8–48,000 characters. The multipart request limit is 10 MiB; JSON requests are limited to 128 KiB. Discovery reports current public limits.

HTTP statusWhat to do
400 / 415 / 422Correct the request format or fields. No work was accepted.
409The idempotency key conflicts with a previous request. Do not silently replace it.
413Reduce upload or text size.
429Respect Retry-After. Rolling daily limits may take up to 24 hours to clear.
503Submissions are disabled or temporarily unavailable. Documentation remains available.

If the submission response is lost, retry the identical request with the same key. Do not automatically resubmit failed or interrupted work, or retry a delivery marked uncertain; doing so may duplicate work or emails.

For exact fields, types, responses and receipt statuses, see the OpenAPI 3.1 schema.