How to Connect DAVE to an Existing System by REST

Summary

The steps

1. 1

   Understand the two integration directions before you build

   Before writing a single line of code or opening the workflow editor, map out which direction each integration requirement runs. Getting this wrong means building in the wrong place and discovering the mistake after the workflow is already active.

   There are two directions:

   • Outbound: DAVE calls your system. A workflow node makes an HTTP request to an external API during workflow execution. This is handled by the API Call node inside the workflow graph. Use this direction when the workflow needs data from your system (a customer record, a product price, a document from a file store) or needs to push a result back to your system (writing an approved output to a database, posting a notification to a webhook, updating a record in a CRM).
   • Inbound: your system calls DAVE. Your code makes an HTTP request to one of DAVE's 305 REST API endpoints. Use this direction when your system needs to trigger a workflow instance (for example, when a new order arrives in your ERP), check the status of a running instance, retrieve a completed result, or manage DAVE resources (users, workflows, agents) programmatically.

   Most real integrations use both directions. A common pattern: your system calls DAVE's REST API to start a workflow instance (inbound), the workflow calls your system's API to fetch context data (outbound), a human reviewer approves the result, and the workflow calls your system's API again to write the approved output (outbound). Map the full data flow before you start building either side.

   Do this

   • Draw the data flow on paper or in a diagram tool: what triggers the workflow, what data flows in, what data flows out, and where it goes.
   • Identify each HTTP call and label it as inbound (your system calls DAVE) or outbound (DAVE calls your system).
   • List the external API endpoints your workflow will need to call, and confirm they are accessible from DAVE's hosted environment over HTTPS.
   • Confirm that the DAVE REST endpoints your code will call are among the 305 available endpoints. Consult the DAVE API reference for the full endpoint list.

   Example

   A legal team uses DAVE to review contract clauses. When a new contract is uploaded to the document management system, the DMS calls DAVE's REST API to start a workflow instance, passing the contract ID as a parameter (inbound). The workflow's API Call node fetches the contract text from the DMS using the contract ID (outbound). An AI agent extracts the clauses. A human reviewer approves or flags them. The workflow's second API Call node writes the review result back to the DMS (outbound). The DMS then notifies the legal team. DAVE handles the AI and review steps; the DMS handles storage and notification.

   Best practice

   • Keep the integration boundary clean: DAVE handles AI processing and human review; your system handles storage, notification, and business logic.
   • Design the outbound calls to be idempotent where possible: if a workflow instance is retried, the API Call node will fire again, and your system should handle duplicate writes gracefully.
   • Do not embed business logic in the workflow graph that belongs in your system, and vice versa. The workflow graph should describe the review process, not replicate your system's data model.
2. 2

   Authenticate inbound calls: JWT and API key options

   Every inbound call to DAVE's REST API must be authenticated. DAVE supports two authentication methods for API access: JWT (JSON Web Token) and API key. Choose the method that fits your integration's security model.

   JWT authentication is the same token-based mechanism used by the DAVE web application. A JWT is issued when a user authenticates, is scoped to the tenant, and expires after the configured session timeout (5 to 1440 minutes, default 60 minutes). For server-to-server integrations that need to act on behalf of a specific user, JWT is appropriate if your integration can handle token refresh. Tokens are not interchangeable across tenants: a token issued for one workspace cannot be used to call another workspace's endpoints.

   API key authentication is the recommended method for server-to-server integrations. API keys are long-lived credentials that do not expire on a session timeout, making them suitable for automated systems that call DAVE without a user present. API keys are scoped to the tenant and carry the permissions of the role assigned to them.

   Both methods pass the credential in the HTTP Authorization header using the Bearer scheme:

   Authorization: Bearer <your-token-or-api-key>

   All API calls must be made over HTTPS. HTTP is not supported.

   Do this

   • Decide whether your integration will use JWT or API key authentication. For automated server-to-server calls, use an API key.
   • For API key authentication, navigate to the API keys or credentials section of your DAVE workspace to generate a key. Consult the DAVE API reference for the exact path, as the workflows help document does not describe API key management in detail.
   • Store the API key in a secrets manager or environment variable. Never hardcode it in source code or commit it to version control.
   • Include the Authorization header on every inbound API request: Authorization: Bearer <key>.
   • Confirm that the role associated with your API key has the permissions required for the endpoints your integration will call. An API key with the Use role can start workflow instances but cannot create or edit workflows.

   Example

   A Python script that triggers a DAVE workflow instance on a schedule uses an API key stored in an environment variable. The script reads the key from the environment, constructs the Authorization header, and calls the DAVE REST endpoint to create a new workflow instance. If the key is rotated, only the environment variable needs to be updated: the script code does not change.

   import os, requests
   
   DAVE_API_KEY = os.environ['DAVE_API_KEY']
   DAVE_BASE_URL = 'https://your-workspace.hellodave.ai'
   
   response = requests.post(
    f'{DAVE_BASE_URL}/api/workflow-instances',
    headers={'Authorization': f'Bearer {DAVE_API_KEY}'},
    json={'workflowId': 'wf_abc123', 'input': {'contractId': '9876'}}
   )
   print(response.json())

   Note: the exact endpoint path and request body shape should be confirmed against the DAVE API reference. The pattern above illustrates the authentication approach.

   Best practice

   • Use API keys for automated integrations, not user JWTs. User JWTs expire and require re-authentication; API keys do not.
   • Assign the minimum role necessary to the API key. If the integration only starts workflow instances, use a key with the Use role. Do not use an Admin-scoped key for routine automation.
   • Rotate API keys on a schedule and whenever a team member with access to the key leaves the organization.
   • Log every inbound API call from your system with the response status code. If DAVE returns a 4xx or 5xx, your system should alert and retry with exponential backoff.
3. 3

   Trigger a workflow instance from your system (inbound)

   The most common inbound integration pattern is triggering a workflow instance when an event occurs in your system. A new order arrives, a document is uploaded, a record changes state: your system detects the event and calls DAVE's REST API to start a workflow instance, passing the relevant data as input.

   DAVE exposes 305 REST API endpoints covering the full platform surface: workflows, instances, tasks, agents, users, roles, credentials, and more. The endpoint for creating a workflow instance accepts a workflow ID and an input payload. The input payload becomes the initial context for the workflow, available to every node in the graph from the first step.

   The general shape of an instance creation request is an HTTP POST to the workflow instances endpoint, with the workflow ID and the input data in the request body. The response includes the instance ID, which your system should store: it is the reference you will use to check instance status and retrieve results.

   After triggering the instance, your system has two options for learning when it completes: polling and webhooks. Polling means calling the instance status endpoint on a schedule until the status changes to completed, failed, or cancelled. Webhooks (if configured) mean DAVE calls your system when the instance status changes. Consult the DAVE API reference for webhook configuration options, as the workflows help document does not describe this in detail.

   Do this

   • Identify the workflow ID for the workflow you want to trigger. The workflow ID is visible in the workflow editor URL: /dashboard/workflows/{id}/editor.
   • Determine what input data the workflow needs. This is defined by the User Interaction node at the start of the workflow: the fields it expects are the fields your system must supply in the input payload.
   • Construct the POST request to the DAVE workflow instances endpoint with the Authorization header and the input payload. Confirm the exact endpoint path and request body schema in the DAVE API reference.
   • Store the instance ID from the response in your system. Use it to poll for status or to correlate webhook events with the original trigger.
   • Implement a retry strategy for failed requests. If the DAVE API returns a 5xx, retry with exponential backoff. If it returns a 4xx, log the error and alert: a 4xx usually indicates a configuration problem (wrong workflow ID, missing required input field, insufficient permissions).

   Example

   An e-commerce platform triggers a DAVE content review workflow whenever a new product description is submitted. The platform's backend sends a POST request to DAVE with the product ID and description text. DAVE returns an instance ID. The platform stores the instance ID against the product record. A background job polls the DAVE instance status endpoint every 30 seconds. When the status changes to completed, the job fetches the approved description from the instance result and updates the product record. If the status changes to failed or cancelled, the job flags the product for manual review.

   Best practice

   • Pass only the data the workflow actually needs in the input payload. Do not send entire database records: extract the fields the workflow uses and send those.
   • Validate the input payload against the workflow's expected schema before sending. A missing required field will cause the workflow instance to fail immediately, and the error will be easier to diagnose if caught before the API call.
   • Store the instance ID durably. If your system restarts between triggering the instance and receiving the result, you need the instance ID to resume polling.
   • Set a maximum polling duration. If an instance has not completed after a reasonable time (for example, 24 hours for a human review workflow), alert and escalate rather than polling indefinitely.
4. 4

   Call your system from inside a workflow (outbound via API Call node)

   The API Call node is one of DAVE's ten workflow node types. It makes an outbound HTTP request to an external URL during workflow execution and passes the response into the workflow context for subsequent nodes to use. This is the mechanism for fetching data from your system before an AI agent processes it, or for writing results back to your system after a human reviewer approves them.

   The API Call node is configured in the workflow editor. At minimum, you specify the HTTP method (GET, POST, PUT, PATCH, or DELETE), the target URL, and any headers or request body the external API requires. The response from the external API is captured and made available to subsequent nodes in the workflow graph.

   For APIs that require authentication, the recommended approach is to store the credential in DAVE's per-tenant encrypted credential vault (using AES-256-GCM authenticated encryption) and reference it in the API Call node's header configuration. Credentials stored in the vault are never returned through the API once stored, and are not visible in the workflow editor after saving. This keeps the external API key out of the workflow graph definition and out of the audit log.

   The API Call node can be placed anywhere in the workflow graph where an outbound HTTP call is needed. Common placements are immediately after the Start node (to fetch context data before the first AI step) and immediately before the End node (to write the approved result back to the external system).

   Do this

   • In the workflow editor, add an API Call node to the graph at the point where the outbound call should occur.
   • Configure the node with the HTTP method, target URL, and any required headers. For authenticated APIs, reference the credential from the tenant vault rather than hardcoding the key in the URL or header field.
   • Store the external API credential in the DAVE credential vault before configuring the node. Navigate to the credentials or secrets section of your workspace to add the credential. Consult the DAVE API reference for the exact path.
   • Test the API Call node in draft mode before activating the workflow. Run a test instance from the editor and inspect the node's output to confirm the external API responded correctly and the response data is available to subsequent nodes.
   • Handle error responses from the external API in the workflow graph. If the API Call node receives a 4xx or 5xx response, a Routing node can branch the workflow to an error path rather than allowing it to proceed with missing data.

   Example

   A contract review workflow uses two API Call nodes. The first, placed after the Start node, calls the document management system's REST API with the contract ID from the workflow input, and receives the contract text in the response. The AI agent then processes the contract text. After the human reviewer approves the extracted clauses, the second API Call node calls the DMS again with a POST request, writing the approved clause summary back to the contract record. Both API Call nodes use credentials stored in the DAVE vault: the DMS API key is never visible in the workflow graph.

   Best practice

   • Always store external API credentials in the DAVE credential vault. Never put API keys, passwords, or tokens directly in the API Call node's URL or header fields.
   • Set a timeout on the API Call node. If the external API does not respond within the timeout period, the node should fail gracefully rather than leaving the workflow instance hanging.
   • Design the external API endpoint to be idempotent for write operations. If the workflow instance is retried, the API Call node will fire again. Your system should handle duplicate writes without creating duplicate records.
   • Log the API Call node's response status in the workflow context. A Routing node downstream can check the status and branch to an error path if the external API returned an error code.
5. 5

   Test the integration end to end before activating

   An integration that works in isolation on each side does not necessarily work when both sides are connected. End-to-end testing before activating the workflow catches the problems that unit testing misses: mismatched field names between the input payload and the workflow's expected schema, external API responses in an unexpected format, authentication failures that only appear in the production environment, and timing issues in polling logic.

   DAVE's draft workflow status is designed for exactly this testing phase. A workflow in draft status can be instantiated from the editor for testing but is not available to the production Use role. This means you can run full end-to-end tests, including live calls to the external API via the API Call node, without exposing the workflow to production traffic.

   The correct end-to-end test sequence for a REST integration is:

   1. With the workflow in draft status, run a test instance from the editor using a representative input payload. Observe each node's execution in the editor and confirm the API Call node receives the expected response from the external API.
   2. From your system, call DAVE's REST API to trigger a test instance of the draft workflow (if the API supports draft instance creation; consult the DAVE API reference). Confirm that the instance ID is returned and stored correctly by your system.
   3. Poll the instance status endpoint from your system and confirm that the status transitions correctly as the workflow progresses.
   4. If the workflow includes a human review step, complete the review task in the DAVE Task Inbox and confirm that the workflow proceeds to the next step and that the outbound API Call node fires correctly after approval.
   5. Confirm that the final result is written correctly to the external system by the outbound API Call node.

   Only activate the workflow after all five steps complete without errors on a representative set of test inputs. Once the workflow is active, it is available to the production Use role and cannot be moved back to draft status.

   Do this

   • Prepare a set of representative test inputs: a standard case, an edge case, and a case that should trigger an error path (for example, an external API that returns a 404).
   • Run each test case from the workflow editor in draft mode. Inspect each node's output to confirm the data flows correctly through the graph.
   • Test the inbound trigger from your system against the draft workflow. Confirm the instance ID is returned and your system stores it correctly.
   • Test the polling or webhook logic from your system. Confirm that your system correctly detects when the instance completes and retrieves the result.
   • Test the error paths. Simulate an external API failure and confirm that the workflow routes to the error path and that your system handles the failed or cancelled instance status correctly.
   • Only change the workflow status to active after all test cases pass.

   Example

   A team building a supplier onboarding integration runs five test cases before activating: a complete supplier record (standard case), a supplier record with a missing optional field (edge case), a supplier record that triggers the AI agent's "requires review" output (human review path), a simulated DMS API timeout (error path), and a simulated duplicate submission (idempotency test). All five pass in draft mode. The workflow is activated. The first production instance runs the following day without errors.

   Best practice

   • Test error paths explicitly, not just the happy path. The happy path almost always works. The error paths are where integrations fail in production.
   • Use realistic test data, not placeholder strings. An API Call node that works with "contractId": "test" may fail with a real contract ID if the external API validates the format.
   • Document the test results before activating. A record of which test cases were run and what the results were is useful evidence if the integration is later audited or questioned.
   • Keep the workflow in draft until all test cases pass. The temptation to activate early and fix issues in production is the most common source of integration incidents.

What this guide covers and when to use it

The API Call node: outbound HTTP from inside a workflow

DAVE's 305 REST API endpoints: inbound control from your code

Role and permission requirements for REST integrations

Frequently asked questions about REST integration with DAVE