Skip to main content
This guide walks you through generating a complete connector from API documentation. You’ll learn the end-to-end workflow from creating a session to generating Groovy code.

​
Prerequisites

Before you begin, ensure you have:
  • Access to the midPilot Connector Generator API (default: http://localhost:8090)
  • API documentation for your target system (URL or file)
  • Basic understanding of REST APIs

​
Complete Workflow

1

Create a Session

Every connector generation starts with a session. Sessions store all your work including documentation, extracted schemas, and generated code.
curl -X POST http://localhost:8090/api/v1/session \
  -H "Content-Type: application/json"
Response:
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Session created successfully. Use this session_id in subsequent requests."
}
Save the sessionId - you’ll use it in all subsequent requests.
2

Upload or Scrape Documentation

You can either upload documentation files or scrape from URLs.
curl -X POST http://localhost:8090/api/v1/session/{sessionId}/documentation \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]"
Response:
{
  "jobId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
Documentation processing happens asynchronously. The system chunks, processes, and analyzes the documentation using LLMs. Check the job status to know when it’s ready.
3

Extract Object Classes

Identify the main object types (User, Group, etc.) in your API.
curl -X POST http://localhost:8090/api/v1/digester/{sessionId}/classes
Response:
{
  "jobId": "8d7f5689-8536-51ef-b05c-f18ed2g01bf8"
}
Check the status and retrieve results:
curl http://localhost:8090/api/v1/digester/{sessionId}/classes?jobId={jobId}
Example Result:
{
  "status": "finished",
  "result": {
    "objectClasses": [
      {
        "name": "User",
        "description": "User account object",
        "relevant": true,
        "relevantChunks": [
          {"docUuid": "abc-123"}
        ]
      },
      {
        "name": "Group",
        "description": "Group object for managing permissions",
        "relevant": true,
        "relevantChunks": [
          {"docUuid": "def-456"}
        ]
      }
    ]
  }
}
4

Extract Attributes and Endpoints

For each object class, extract its attributes and API endpoints.
curl -X POST http://localhost:8090/api/v1/digester/{sessionId}/classes/User/attributes
Attributes Response:
{
  "status": "finished",
  "result": {
    "attributes": {
      "id": {
        "type": "string",
        "required": true,
        "readOnly": false,
        "multivalued": false
      },
      "username": {
        "type": "string",
        "required": true,
        "readOnly": false,
        "multivalued": false
      },
      "email": {
        "type": "string",
        "required": true,
        "readOnly": false,
        "multivalued": false
      }
    }
  }
}
Endpoints Response:
{
  "status": "finished",
  "result": {
    "endpoints": [
      {
        "operation": "list",
        "method": "GET",
        "path": "/api/v1/users",
        "description": "List all users"
      },
      {
        "operation": "get",
        "method": "GET",
        "path": "/api/v1/users/{id}",
        "description": "Get user by ID"
      },
      {
        "operation": "create",
        "method": "POST",
        "path": "/api/v1/users",
        "description": "Create a new user"
      }
    ]
  }
}
5

Generate Connector Code

Generate Groovy connector code for CRUD operations.
curl -X POST http://localhost:8090/api/v1/codegen/{sessionId}/classes/User/search/all
Generated Code Example:
// Search/List Users
def users = []
def response = httpClient.get("/api/v1/users")
response.data.each { user ->
    users.add([
        __UID__: user.id,
        __NAME__: user.username,
        email: user.email
    ])
}
return users
6

Generate Native Schema and ConnID

Create the native schema definition and ConnID mappings.
curl -X POST http://localhost:8090/api/v1/codegen/{sessionId}/classes/User/native-schema

​
Checking Job Status

All extraction and generation operations are asynchronous. Monitor job progress: 
curl http://localhost:8090/api/v1/digester/{sessionId}/classes?jobId={jobId}
Status Values:
  • queued - Job is waiting to be processed
  • running - Job is currently executing
  • finished - Job completed successfully
  • failed - Job encountered an error

​
What’s Next?

Architecture Overview

Understand the system components and how they work together

API Reference

Explore all available API endpoints

Configuration

Configure LLM providers and system settings

Core Concepts

Learn about sessions, workflows, and job tracking

​
Common Patterns

​
Processing Multiple Object Classes

# 1. Extract all classes
curl -X POST http://localhost:8090/api/v1/digester/{sessionId}/classes

# 2. For each relevant class, extract details
for class in User Group Role; do
  curl -X POST http://localhost:8090/api/v1/digester/{sessionId}/classes/$class/attributes
  curl -X POST http://localhost:8090/api/v1/digester/{sessionId}/classes/$class/endpoints
done

# 3. Generate code for each class
for class in User Group Role; do
  curl -X POST http://localhost:8090/api/v1/codegen/{sessionId}/classes/$class/search/all
  curl -X POST http://localhost:8090/api/v1/codegen/{sessionId}/classes/$class/create
  curl -X POST http://localhost:8090/api/v1/codegen/{sessionId}/classes/$class/update
  curl -X POST http://localhost:8090/api/v1/codegen/{sessionId}/classes/$class/delete
done

​
Handling Relations

# Extract relations between object classes
curl -X POST http://localhost:8090/api/v1/digester/{sessionId}/relations

# Generate relation code
curl -X POST http://localhost:8090/api/v1/codegen/{sessionId}/relations/UserGroupMembership
Always wait for jobs to complete before requesting dependent operations. For example, attributes and endpoints extraction requires object classes to be extracted first.

Build docs developers (and LLMs) love

Get started for freeTalk to us