Skip to main content
Parameter mapping controls how input data is transformed into HTTP requests. Map input fields to path parameters, query strings, headers, and request bodies.

​
Mapping Locations

REST operations support four parameter locations:
LocationUsageExample
PathURL path variables/users/{id}
QueryURL query string?limit=10&offset=0
BodyRequest body{"name": "Alice"}
HeaderHTTP headersAuthorization: Bearer ...

​
Path Parameters

Parameters embedded in URL path. 
/api/users/{id}/posts/{postId}
Mapping configuration: 
{
  "path_params": [
    {
      "name": "id",
      "from_field": "user_id",
      "required": true,
      "param_type": "string"
    },
    {
      "name": "postId",
      "from_field": "post_id",
      "required": true,
      "param_type": "integer"
    }
  ]
}
When agent calls operation with {"user_id": "123", "post_id": "456"}: 
GET /api/users/123/posts/456

​
Query Parameters

Parameters in URL query string. 
/api/search?query=python&limit=10&offset=0
Mapping configuration: 
{
  "query_params": [
    {
      "name": "query",
      "from_field": "search_term",
      "required": true
    },
    {
      "name": "limit",
      "from_field": "page_limit",
      "required": false,
      "param_type": "integer"
    },
    {
      "name": "offset",
      "from_field": "page_offset",
      "required": false,
      "param_type": "integer"
    }
  ]
}
When agent calls with {"search_term": "python", "page_limit": 10}: 
GET /api/search?query=python&limit=10

​
Body Parameters

Request body mapping controls how input becomes JSON/form data.

​
Strategy: Full Input

Use entire input as body: 
{
  "body_config": {
    "strategy": "full_input",
    "content_type": "application/json"
  }
}
Agent input: {"name": "Alice", "email": "alice@example.com"} Request body: 
{
  "name": "Alice",
  "email": "alice@example.com"
}

​
Strategy: From Field

Extract specific field: 
{
  "body_config": {
    "strategy": "from_field",
    "field": "data"
  }
}
Agent input: {"data": {"name": "Alice"}} Request body: {"name": "Alice"}

​
Strategy: Mapped

Map individual fields: 
{
  "body_config": {
    "strategy": "mapped",
    "mappings": [
      {
        "to_field": "full_name",
        "from_field": "name",
        "required": true
      },
      {
        "to_field": "email_address",
        "from_field": "email",
        "required": true
      }
    ]
  }
}
Agent input: {"name": "Alice", "email": "alice@example.com"} Request body: 
{
  "full_name": "Alice",
  "email_address": "alice@example.com"
}

​
Header Parameters

Add custom headers to requests: 
{
  "header_params": [
    {
      "name": "X-Custom-Header",
      "from_field": "custom_value",
      "required": false
    },
    {
      "name": "X-Request-ID",
      "from_field": "request_id",
      "required": true
    }
  ]
}

​
Nested Field Mapping

Map nested input fields using dot notation or arrays: 
{
  "path_params": [
    {
      "name": "id",
      "from_field": ["user", "profile", "id"],
      "required": true
    }
  ]
}
Agent input: 
{
  "user": {
    "profile": {
      "id": "123"
    }
  }
}
Extracted value: "123" Or using dot notation: 
{
  "from_field": "user.profile.id"
}

​
Parameter Validation

Add validation to parameters: 
{
  "path_params": [
    {
      "name": "id",
      "from_field": "user_id",
      "required": true,
      "param_type": "string",
      "pattern": "^[a-z0-9]+$",
      "minimum": null,
      "maximum": null,
      "enum_values": null
    }
  ]
}
Validation options:
  • pattern - Regex for strings
  • minimum - Min value for numbers
  • maximum - Max value for numbers
  • enum_values - Allowed values list

​
Complex Example: GitHub Create Issue

Operation: POST /repos/{owner}/{repo}/issues Full mapping: 
{
  "path_params": [
    {
      "name": "owner",
      "from_field": "repo_owner",
      "required": true
    },
    {
      "name": "repo",
      "from_field": "repo_name",
      "required": true
    }
  ],
  "query_params": [
    {
      "name": "per_page",
      "from_field": "items_per_page",
      "required": false
    }
  ],
  "header_params": [
    {
      "name": "Authorization",
      "from_field": "auth_token",
      "required": true
    }
  ],
  "body_config": {
    "strategy": "mapped",
    "mappings": [
      {
        "to_field": "title",
        "from_field": "issue_title",
        "required": true
      },
      {
        "to_field": "body",
        "from_field": "issue_body",
        "required": false
      },
      {
        "to_field": "assignees",
        "from_field": "assigned_users",
        "required": false
      },
      {
        "to_field": "labels",
        "from_field": "issue_labels",
        "required": false
      }
    ]
  }
}
Agent input: 
{
  "repo_owner": "openai",
  "repo_name": "gpt-4",
  "issue_title": "Feature request",
  "issue_body": "Please add...",
  "assigned_users": ["alice"],
  "auth_token": "ghp_..."
}
Generated request: 
POST /repos/openai/gpt-4/issues?per_page=20
Authorization: ghp_...

{
  "title": "Feature request",
  "body": "Please add...",
  "assignees": ["alice"]
}

​
Type Conversion

Parameters are automatically converted: 
{
  "query_params": [
    {
      "name": "limit",
      "from_field": "limit",
      "param_type": "integer"
    }
  ]
}
If agent provides "limit": "10" (string), auto-converted to integer 10. Supported types:
  • string
  • integer
  • number (float)
  • boolean
  • array
  • object

​
Default Values

Set defaults for optional parameters: 
{
  "query_params": [
    {
      "name": "limit",
      "from_field": "limit",
      "required": false,
      "default": 10
    }
  ]
}
If agent doesn’t provide limit, defaults to 10.

​
Testing Mappings

After configuring mappings:
  1. Connectors > Select connector
  2. Click Test
  3. Select operation
  4. Provide sample input
  5. View generated request
  6. Verify mapping correct
Check:
  • Values in correct locations
  • Data types correct
  • Nested fields extracted correctly
  • Validation applied

​
Common Mapping Patterns

​
Simple Path + Query

{
  "path_params": [{"name": "id", "from_field": "id"}],
  "query_params": [{"name": "filter", "from_field": "filter"}]
}

​
Body with Headers

{
  "body_config": {"strategy": "mapped"},
  "header_params": [{"name": "Authorization", "from_field": "token"}]
}

​
Nested Path

{
  "path_params": [
    {"name": "id", "from_field": ["user", "id"]}
  ]
}

​
Debugging Mapping Issues

​
Values in wrong location

  • Check from_field mapping
  • Verify parameter name matches API docs
  • Review request in Test tab

​
Missing values

  • Ensure required: true only on required fields
  • Check agent provides necessary input
  • Verify field names in agent input

​
Type errors

  • Specify correct param_type
  • Ensure input data type matches
  • Check API documentation

​
Next Steps