API Reference

Complete API reference for Wraft integration

Wraft API Reference

The Wraft API provides programmatic access to all core functionality, enabling you to integrate document automation into your existing applications and workflows.

🔑 Authentication

Wraft uses API tokens for authentication. Include your token in the Authorization header of all requests.

Authorization: Bearer YOUR_API_TOKEN

Getting Your API Token

  1. Log into your Wraft workspace
  2. Go to Settings → API Tokens
  3. Click Generate New Token
  4. Copy and store the token securely

Security: API tokens provide full access to your workspace. Store them securely and rotate them regularly.

🌐 Base URL

All API requests should be made to:

https://api.wraft.com/v1

For self-hosted instances:

https://your-domain.com/api/v1

📊 Core Resources

🏢 Workspaces

Manage workspace settings and configurations

📄 Templates

Create and manage document templates

📝 Forms

Build and deploy data collection forms

🔄 Pipelines

Automate document generation workflows

📋 Documents

Generate and manage documents

👥 Users

Manage workspace members and permissions

🏢 Workspaces

List Workspaces

GET /workspaces

Response:

{
  "data": [
    {
      "id": "ws_1234567890",
      "name": "My Workspace",
      "description": "Primary workspace for document automation",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-20T15:30:00Z",
      "settings": {
        "timezone": "UTC",
        "default_theme": "corporate"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Get Workspace Details

GET /workspaces/{workspace_id}

Parameters:

  • workspace_id (string): Unique workspace identifier

Create Workspace

POST /workspaces

Request Body:

{
  "name": "New Workspace",
  "description": "Workspace for new project",
  "settings": {
    "timezone": "America/New_York",
    "default_theme": "modern"
  }
}

📄 Templates

List Templates

GET /workspaces/{workspace_id}/templates

Query Parameters:

  • page (integer): Page number (default: 1)
  • per_page (integer): Items per page (default: 25, max: 100)
  • search (string): Search templates by name or content
  • category (string): Filter by template category

Example:

curl -H "Authorization: Bearer $TOKEN" \
     "https://api.wraft.com/v1/workspaces/ws_123/templates?search=contract&page=1"

Get Template

GET /workspaces/{workspace_id}/templates/{template_id}

Response:

{
  "id": "tpl_1234567890",
  "name": "Service Agreement",
  "description": "Standard service agreement template",
  "content": "# Service Agreement\n\n**Client:** {{client_name}}...",
  "variables": [
    {
      "name": "client_name",
      "type": "text",
      "required": true,
      "description": "Client's full name"
    },
    {
      "name": "start_date",
      "type": "date",
      "required": true,
      "description": "Project start date"
    }
  ],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-20T15:30:00Z"
}

Create Template

POST /workspaces/{workspace_id}/templates

Request Body:

{
  "name": "New Template",
  "description": "Template description",
  "content": "# Document Title\n\nContent with {{variable_name}}",
  "category": "contracts",
  "variables": [
    {
      "name": "variable_name",
      "type": "text",
      "required": true,
      "description": "Variable description"
    }
  ]
}

Update Template

PUT /workspaces/{workspace_id}/templates/{template_id}

Delete Template

DELETE /workspaces/{workspace_id}/templates/{template_id}

📝 Forms

List Forms

GET /workspaces/{workspace_id}/forms

Create Form

POST /workspaces/{workspace_id}/forms

Request Body:

{
  "name": "Client Information Form",
  "description": "Collect client details for contract generation",
  "fields": [
    {
      "name": "client_name",
      "type": "text",
      "label": "Client Name",
      "required": true,
      "validation": {
        "min_length": 2,
        "max_length": 100
      }
    },
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true
    },
    {
      "name": "project_start",
      "type": "date",
      "label": "Project Start Date",
      "required": true
    }
  ],
  "settings": {
    "allow_multiple_submissions": false,
    "require_authentication": true
  }
}

Submit Form Data

POST /workspaces/{workspace_id}/forms/{form_id}/submissions

Request Body:

{
  "data": {
    "client_name": "Acme Corporation",
    "email": "contact@acme.com",
    "project_start": "2024-02-01"
  },
  "metadata": {
    "submitted_by": "user@example.com",
    "submission_source": "api"
  }
}

🔄 Pipelines

List Pipelines

GET /workspaces/{workspace_id}/pipelines

Create Pipeline

POST /workspaces/{workspace_id}/pipelines

Request Body:

{
  "name": "Contract Generation Pipeline",
  "description": "Automatically generate contracts from form submissions",
  "trigger": {
    "type": "form_submission",
    "form_id": "frm_1234567890"
  },
  "steps": [
    {
      "type": "data_validation",
      "config": {
        "required_fields": ["client_name", "email", "project_start"]
      }
    },
    {
      "type": "template_processing",
      "config": {
        "template_id": "tpl_1234567890",
        "output_format": "pdf"
      }
    },
    {
      "type": "email_delivery",
      "config": {
        "to": "{{email}}",
        "subject": "Your Contract - {{client_name}}",
        "template": "contract_delivery"
      }
    }
  ]
}

Execute Pipeline

POST /workspaces/{workspace_id}/pipelines/{pipeline_id}/execute

Request Body:

{
  "data": {
    "client_name": "Acme Corporation",
    "email": "contact@acme.com",
    "project_start": "2024-02-01",
    "project_value": 50000
  },
  "options": {
    "async": true,
    "webhook_url": "https://your-app.com/webhooks/pipeline-complete"
  }
}

📋 Documents

Generate Document

POST /workspaces/{workspace_id}/documents/generate

Request Body:

{
  "template_id": "tpl_1234567890",
  "data": {
    "client_name": "Acme Corporation",
    "contract_date": "2024-01-15",
    "project_name": "Website Redesign",
    "total_amount": 25000
  },
  "options": {
    "format": "pdf",
    "theme": "corporate",
    "filename": "contract_acme_2024.pdf"
  }
}

Response:

{
  "document_id": "doc_1234567890",
  "status": "completed",
  "download_url": "https://api.wraft.com/v1/documents/doc_1234567890/download",
  "expires_at": "2024-01-22T10:00:00Z",
  "metadata": {
    "format": "pdf",
    "size_bytes": 245760,
    "pages": 3
  }
}

Download Document

GET /documents/{document_id}/download

Response: Binary file content

List Documents

GET /workspaces/{workspace_id}/documents

Query Parameters:

  • status (string): Filter by status (pending, processing, completed, failed)
  • template_id (string): Filter by template
  • created_after (datetime): Filter by creation date
  • format (string): Filter by output format

👥 Users & Permissions

List Workspace Members

GET /workspaces/{workspace_id}/members

Invite User

POST /workspaces/{workspace_id}/members/invite

Request Body:

{
  "email": "newuser@example.com",
  "role": "editor",
  "permissions": [
    "templates.create",
    "templates.edit",
    "forms.create",
    "documents.generate"
  ],
  "message": "Welcome to our document automation workspace!"
}

🔄 Webhooks

Configure webhooks to receive real-time notifications about events in your workspace.

Supported Events

Form Submission

form.submitted

Triggered when a form is submitted

Document Generated

document.generated

Triggered when document generation completes

Pipeline Executed

pipeline.executed

Triggered when a pipeline finishes execution

Template Updated

template.updated

Triggered when a template is modified

Configure Webhook

POST /workspaces/{workspace_id}/webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/wraft",
  "events": [
    "form.submitted",
    "document.generated",
    "pipeline.executed"
  ],
  "secret": "your_webhook_secret",
  "active": true
}

Webhook Payload Example

{
  "event": "document.generated",
  "timestamp": "2024-01-15T10:30:00Z",
  "workspace_id": "ws_1234567890",
  "data": {
    "document_id": "doc_1234567890",
    "template_id": "tpl_1234567890",
    "status": "completed",
    "download_url": "https://api.wraft.com/v1/documents/doc_1234567890/download"
  }
}

📊 Rate Limits

Rate Limits: API requests are limited to prevent abuse and ensure service quality.

PlanRequests per minuteConcurrent requests
Free605
Pro30015
Enterprise100050

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 285
X-RateLimit-Reset: 1640995200

🚨 Error Handling

HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
422Validation Error
429Rate Limited
500Server Error

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "The request data is invalid",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ],
    "request_id": "req_1234567890"
  }
}

🛠️ SDKs & Libraries

JavaScript/Node.js

npm install @wraft/sdk

Python

pip install wraft-python

Ruby

gem install wraft

PHP

composer require wraft/wraft-php

JavaScript Example

import Wraft from '@wraft/sdk';
 
const wraft = new Wraft({
  apiToken: process.env.WRAFT_API_TOKEN,
  workspace: 'ws_1234567890'
});
 
// Generate document
const document = await wraft.documents.generate({
  templateId: 'tpl_1234567890',
  data: {
    client_name: 'Acme Corp',
    project_value: 50000
  },
  format: 'pdf'
});
 
console.log('Document generated:', document.downloadUrl);

Python Example

from wraft import WraftClient
 
client = WraftClient(
    api_token=os.getenv('WRAFT_API_TOKEN'),
    workspace='ws_1234567890'
)
 
# Generate document
document = client.documents.generate(
    template_id='tpl_1234567890',
    data={
        'client_name': 'Acme Corp',
        'project_value': 50000
    },
    format='pdf'
)
 
print(f'Document generated: {document.download_url}')

🧪 Testing

API Explorer

Use our interactive API explorer to test endpoints:

https://api.wraft.com/explorer

Postman Collection

Import our Postman collection for easy testing:

https://api.wraft.com/postman-collection.json

Test Environment

Use our sandbox environment for development:

https://sandbox-api.wraft.com/v1

Sandbox: The sandbox environment resets daily and doesn't count against rate limits.

📚 Additional Resources

🔧 Integration Guides

Step-by-step integration tutorials

📖 API Changelog

Track API updates and changes

💬 Developer Community

Join our developer Discord

🐛 Report Issues

GitHub issues and bug reports

Previous

Troubleshooting

Next

Introduction

On this page