DenchClaw OpenAPI: Documentation for Developers

If you're building an integration with DenchClaw — a script, a custom UI, an external tool connection — the OpenAPI spec is where you start. It's the machine-readable description of every endpoint, request schema, and response format. Load it into Postman, generate a typed client, or feed it to an AI coding assistant to get working integration code without reading docs manually.

Here's everything you need to work with the DenchClaw OpenAPI spec.

Where to Find the Spec#

The OpenAPI spec ships with DenchClaw and is served at runtime:

http://localhost:4242/api/v1/openapi.json

Or in YAML format:

http://localhost:4242/api/v1/openapi.yaml

Download it locally:

# Download JSON spec
curl http://localhost:4242/api/v1/openapi.json -o denchclaw-openapi.json
 
# Download YAML spec
curl http://localhost:4242/api/v1/openapi.yaml -o denchclaw-openapi.yaml

The spec is also available in the GitHub repository:

https://raw.githubusercontent.com/DenchHQ/denchclaw/main/spec/openapi.yaml

This is the canonical version. Local instances serve a copy generated from the installed version.

Spec Overview#

The DenchClaw OpenAPI spec follows OpenAPI 3.1.0. Here's an abbreviated excerpt showing the structure:

openapi: "3.1.0"
info:
  title: DenchClaw API
  description: Local-first AI CRM API
  version: "1.0.0"
  contact:
    url: https://dench.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
 
servers:
  - url: http://localhost:4242/api/v1
    description: Local instance (default)
  - url: https://{instance}.dench.com/api/v1
    description: Remote instance
    variables:
      instance:
        default: your-instance
 
security:
  - BearerAuth: []
 
paths:
  /objects:
    get:
      operationId: listObjects
      summary: List all CRM objects
      tags: [Objects]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectList'
 
  /objects/{objectName}/entries:
    get:
      operationId: listEntries
      summary: List entries for an object
      tags: [Entries]
      parameters:
        - name: objectName
          in: path
          required: true
          schema:
            type: string
            example: people
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 1000
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: search
          in: query
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/EntryListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
 
    post:
      operationId: createEntry
      summary: Create a new entry
      tags: [Entries]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntryRequest'
      responses:
        '201':
          $ref: '#/components/responses/EntryResponse'
 
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
 
  schemas:
    Entry:
      type: object
      properties:
        id:
          type: string
          example: entry_abc123
        object:
          type: string
          example: people
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        fields:
          type: object
          additionalProperties: true
          example:
            name: "Sarah Chen"
            email: "sarah@acme.com"
            status: "Customer"
 
    CreateEntryRequest:
      type: object
      required: [fields]
      properties:
        fields:
          type: object
          additionalProperties: true
 
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

Importing into Postman#

Postman can import the OpenAPI spec directly and generate a full collection with all endpoints.

Step 1: Download the spec#

curl http://localhost:4242/api/v1/openapi.json -o denchclaw-openapi.json

Step 2: Import into Postman#

1. Open Postman
2. Click Import (top left)
3. Drag denchclaw-openapi.json into the import area (or click Upload Files)
4. Choose OpenAPI 3.0 with a Postman Collection as import option
5. Click Import

Postman creates a collection called "DenchClaw API" with folders for each tag (Objects, Entries, Fields, Webhooks, Documents).

Step 3: Set up authentication#

1. Click on the collection → Authorization tab
2. Type: Bearer Token
3. Token: {{API_KEY}}
4. Click Save

Step 4: Create an environment#

1. Click Environments → New Environment → Name it "DenchClaw Local"
2. Add variable: API_KEY = your actual API key
3. Add variable: BASE_URL = http://localhost:4242/api/v1
4. Save and select the environment

Now all requests in the collection automatically use your API key and base URL.

Importing into Insomnia#

1. Open Insomnia
2. Click Create → Import from File
3. Select denchclaw-openapi.json
4. Insomnia imports all routes as requests
5. Set the Authorization environment variable to Bearer your-api-key

Generating Client SDKs from the Spec#

The OpenAPI spec lets you auto-generate typed clients in any language.

JavaScript/TypeScript with openapi-typescript#

# Install the generator
npm install -g openapi-typescript
 
# Generate TypeScript types from the spec
npx openapi-typescript http://localhost:4242/api/v1/openapi.json -o ./types/denchclaw.d.ts

This generates TypeScript interfaces for all request and response bodies:

import type { paths } from './types/denchclaw.d.ts';
import createClient from 'openapi-fetch';
 
const client = createClient<paths>({
  baseUrl: 'http://localhost:4242/api/v1',
  headers: {
    Authorization: `Bearer ${process.env.DENCH_API_KEY}`
  }
});
 
// Fully typed request + response
const { data, error } = await client.GET('/objects/{objectName}/entries', {
  params: {
    path: { objectName: 'people' },
    query: { limit: 50, filter: { status: 'Lead' } }
  }
});

Python with openapi-generator#

# Install openapi-generator
pip install openapi-generator-cli
 
# Generate Python client
openapi-generator generate \
  -i http://localhost:4242/api/v1/openapi.json \
  -g python \
  -o ./denchclaw-client-python \
  --package-name denchclaw
 
# Use the generated client
cd denchclaw-client-python
pip install -e .

import denchclaw
from denchclaw.api import entries_api
 
config = denchclaw.Configuration(
    host="http://localhost:4242/api/v1",
    access_token="your-api-key"
)
 
with denchclaw.ApiClient(config) as client:
    api = entries_api.EntriesApi(client)
    entries = api.list_entries('people', limit=50)
    for entry in entries.entries:
        print(entry.fields.get('name'))

Go client#

openapi-generator generate \
  -i denchclaw-openapi.json \
  -g go \
  -o ./denchclaw-go-client \
  --package-name denchclaw

Using the Spec with AI Coding Tools#

The OpenAPI spec is especially useful when working with AI coding assistants like Cursor, Claude, or GitHub Copilot. Instead of explaining the API, paste the spec and ask for what you need.

With Cursor#

1. Add the spec to your project: cp denchclaw-openapi.json ./specs/
2. In Cursor: @specs/denchclaw-openapi.json references it in context
3. Ask: "Using the DenchClaw API spec at @specs/denchclaw-openapi.json, write a Python function that creates a new contact and returns the entry ID"

Cursor generates working, typed code based on the actual spec.

With Claude#

Paste the spec (or the relevant portion) directly in the prompt:

Here is the DenchClaw OpenAPI spec (excerpt):
[paste spec]

Write a JavaScript function that:
1. Takes a contact object (name, email, company)
2. Creates a new "people" entry via the DenchClaw API
3. Returns the created entry ID
4. Handles 409 Conflict errors (duplicate email)

With GitHub Copilot#

Add the spec to your project root or a docs/ folder. Copilot picks it up from the workspace context and suggests relevant API calls as you type.

Schema Overview#

The spec defines these main schemas:

The fields property on entries is deliberately typed as additionalProperties: true since field names are dynamic (user-defined). When you know your specific schema, generate a typed wrapper on top.

Versioning Strategy#

DenchClaw follows semantic versioning for its API. The current version is v1.

• Breaking changes (renamed fields, removed endpoints) bump the major version: v2
• Additive changes (new endpoints, new optional fields) are backwards-compatible within v1
• Bug fixes don't change the spec

The version is in the path: /api/v1/.... When v2 launches, v1 will remain available for a deprecation period (minimum 6 months).

The spec itself includes a version field in the info block reflecting the API version. Track changes in the changelog: CHANGELOG.md in the GitHub repo.

Contributing to the Spec#

The OpenAPI spec lives at /spec/openapi.yaml in the DenchClaw repository.

How to contribute#

1. Fork github.com/DenchHQ/denchclaw
2. Edit spec/openapi.yaml
3. Validate your changes: npx @redocly/cli lint spec/openapi.yaml
4. Submit a pull request

Spec contributions that need maintainer review:

• New endpoints
• Changes to existing schemas
• Security scheme changes

Documentation improvements (examples, descriptions) can be merged quickly. Schema changes need to align with the actual implementation.

Generating docs from the spec#

# Generate HTML docs with Redoc
npx @redocly/cli build-docs spec/openapi.yaml -o docs/api.html
 
# Generate interactive docs with Swagger UI
npx swagger-ui-watcher spec/openapi.yaml

The Spec vs the Bridge API#

The OpenAPI spec describes the REST API. The Bridge API (window.dench) is a different interface for Dench Apps running inside the DenchClaw UI.

For integrations running outside DenchClaw, use the REST API (documented by the OpenAPI spec). For custom Dench Apps running inside the platform, use the Bridge API.

FAQ#

Where is the interactive Swagger UI for DenchClaw? Available at http://localhost:4242/api/v1/docs when DenchClaw is running locally.

Does the spec include webhook payload schemas? Yes. The WebhookPayload schema documents the exact structure of outgoing webhook requests, including the event envelope format and data fields.

Can I use the spec to validate API responses in tests? Yes. Tools like jest-openapi or chai-openapi-response-validator validate API responses against the spec automatically.

Is the OpenAPI spec versioned separately from the app? The spec version tracks the API version, which moves with the app. The spec changelog is in the GitHub repo alongside release notes.

Can I host my own copy of the interactive docs? Yes. Download the spec and use any OpenAPI documentation host (Redoc, Swagger UI, Bump.sh, ReadMe.io) to serve it.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →