Skip to main content

Your First Connector

This tutorial walks through creating a connector from start to finish.

Step 1: Find API Documentation​

Before creating a connector, you need the platform's API documentation. Look for:

  • OpenAPI 3.x specification (preferred)
  • Swagger 2.0 specification
  • Postman collection
  • HTML API reference

Good documentation includes:

  • Authentication requirements
  • List of endpoints with parameters
  • Response formats with examples
  • Pagination information
  • Rate limits

Step 2: Start Automated Generation​

  1. Go to Connectors → Generate from API Docs
  2. Choose your input:
    • URL tab: paste a link to an OpenAPI spec, Swagger file, or Postman collection
    • Upload File tab: upload a .json, .yaml, or .yml spec file
  3. Click Generate Connector

The system will:

  1. Parse the API documentation
  2. Identify all endpoints
  3. Analyze each endpoint using AI
  4. Create a draft for your review

You'll watch a progress screen while generation runs; when it completes, click Review Draft to open the draft editor.

Step 3: Review the Draft​

The draft editor (the "Review: {platform}" page) has three tabs: Review Endpoints, Endpoint Explorer, and Test & Configure.

Review Endpoints Tab​

Each endpoint shows:

  • Name: Friendly name (editable)
  • Path: API endpoint path
  • Category: Logical grouping
  • LLM Recommendation: Keep or discard with reasoning
  • Forensic Relevance: Whether this is evidence-worthy data
  • Enabled: Toggle to include/exclude

Review Actions​

  1. Enable/Disable: Toggle endpoints on/off
  2. View Recommendation: Read AI reasoning
  3. Add Notes: Document your decisions
  4. Change Category: Override auto-categorization

Focus on:

  • Enabling endpoints that return user data, messages, files, activity logs
  • Disabling endpoints that modify data or return only configuration
  • Adding notes explaining any non-obvious decisions

Step 4: Configure Pagination​

Switch to the Test & Configure tab, then select an endpoint and open its Paging tab in the endpoint editor.

For each endpoint with list data:

  1. Select the endpoint
  2. Open the Paging tab and enable pagination
  3. Select pagination type based on API behavior:
Response PatternType to Select
next_cursor or cursor fieldCursor
has_more + cursorCursor
next_page_uri (full path)Cursor + enable "Cursor is full URL path"
Uses offset and limit paramsOffset
Uses page numberPage
Link header with rel="next"Link Header

  1. Configure parameter names (from API docs):

    • Cursor param name (e.g., cursor, starting_after)
    • Limit param name (e.g., limit, per_page)
    • Default page size (e.g., 100)

  2. Configure response paths:

    • Path to next cursor (e.g., response_metadata.next_cursor)
    • Path to has_more flag (e.g., has_more)
    • Path to data array (e.g., data, items, members)

  3. Set stop condition:

    • Cursor empty: Stop when cursor is null/empty
    • Boolean flag: Stop when has_more equals false
    • Comparison: Stop when result count is less than limit

See Pagination Reference for detailed examples.

Step 5: Set Up Dependencies​

When an endpoint needs data from another endpoint (like user IDs):

  1. Test the source endpoint first to see its response
  2. In the JSON viewer, click the field containing the values you need
  3. Drag the path to the target endpoint's parameter drop zone
  4. Choose the mode:
    • Iterate: Call target endpoint for each value (most common)
    • First: Use only the first value

Example: Collecting messages from channels​

Step 1: Test "List Channels" endpoint
        Response: { "channels": [{ "id": "C123" }, { "id": "C456" }] }

Step 2: Click "channels[*].id" in the JSON viewer

Step 3: Drag to "Get Channel Messages" endpoint
        Target parameter: channel_id (in path)

Step 4: Select "Iterate" mode
        Result: Will call /channels/C123/messages, /channels/C456/messages

Step 6: Test the Connector​

  1. Add test credentials for the platform
  2. Test individual endpoints to verify they work
  3. Test the dependency chain to verify data flows correctly
  4. Check pagination by verifying multiple pages are retrieved

What to Verify​

  • Credentials authenticate successfully
  • Each enabled endpoint returns data
  • Pagination retrieves all pages (not just first)
  • Dependencies resolve to correct values
  • No rate limit errors occur

Step 7: Create the Connector​

  1. Review all configurations one final time
  2. Click Create Connector (top right of the draft editor — requires at least one enabled endpoint)

This finalizes the draft into a connector at version 1.0.0 with Testing status, and returns you to the connectors list. The version number is assigned automatically; there's no version field to fill in.

Later edits to the published connector are applied via the Publish flow, which bumps the version automatically — see Versioning.

Common Mistakes to Avoid​

1. Forgetting Pagination​

Always configure pagination for endpoints that return lists. Without it, you'll only get the first page of data.

2. Wrong Cursor Path​

Double-check the JSON path to the cursor. If it's wrong, pagination will stop after the first page.

3. Missing Dependencies​

If an endpoint has path parameters like /users/{user_id}, it needs a dependency to provide those values.

4. Enabling Write Endpoints​

Disable any endpoints that modify data (POST, PUT, DELETE to non-list resources). Forensic collection should be read-only.

5. Not Testing with Real Data​

Always test with real credentials and data. Sample responses don't catch all issues.

Next Steps​