> ## Documentation Index
> Fetch the complete documentation index at: https://noorle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# REST Connectors

> Create custom REST API connectors by defining operations and parameter mappings.

REST Connectors expose any HTTP API as tools. Define operations, map parameters, and handle authentication.

## Creating a REST Connector

<Steps>
  <Step title="Navigate to Connectors">
    1. Go to **Connectors**
    2. Click **Create Connector**
    3. Choose **REST API**
  </Step>

  <Step title="Configure Base Settings">
    * **Name** - Identifier (e.g., "Stripe API")
    * **Base URL** - API root (e.g., [https://api.stripe.com/v1](https://api.stripe.com/v1))
    * **Description** - What it does
  </Step>

  <Step title="Define Operations">
    Add each API endpoint as an operation:

    1. Click **Add Operation**
    2. Enter operation name
    3. Choose HTTP method (GET, POST, etc.)
    4. Enter path (e.g., /charges/{id})
    5. Define input JSON schema
    6. Click **Save**
  </Step>

  <Step title="Configure Authentication">
    1. Click **Authentication**
    2. Choose method (Bearer, OAuth, API Key, etc.)
    3. Enter credentials or configure OAuth
    4. Test connection
  </Step>

  <Step title="Test Operations">
    1. Click **Test**
    2. Select operation
    3. Provide sample input
    4. Verify response
  </Step>
</Steps>

## Operation Definition

Each operation maps to an API endpoint:

```json theme={null}
{
  "name": "create_charge",
  "description": "Create a charge",
  "method": "POST",
  "path": "/charges",
  "input_schema": {
    "type": "object",
    "properties": {
      "amount": {"type": "integer"},
      "currency": {"type": "string"},
      "source": {"type": "string"}
    },
    "required": ["amount", "currency", "source"]
  }
}
```

## Parameter Mapping

Map input parameters to HTTP request parts:

### Path Parameters

Parameters in URL path (e.g., `/users/{id}`):

```json theme={null}
{
  "path_params": [
    {
      "name": "id",
      "from_field": "user_id",
      "required": true,
      "param_type": "string"
    }
  ]
}
```

### Query Parameters

Parameters in URL query string:

```json theme={null}
{
  "query_params": [
    {
      "name": "limit",
      "from_field": "page_limit",
      "required": false,
      "param_type": "integer"
    }
  ]
}
```

### Body Parameters

Data in request body:

```json theme={null}
{
  "body_config": {
    "strategy": "mapped",
    "mappings": [
      {
        "to_field": "email",
        "from_field": "user_email",
        "required": true
      }
    ]
  }
}
```

### Header Parameters

Custom headers:

```json theme={null}
{
  "header_params": [
    {
      "name": "X-Custom-Header",
      "from_field": "custom_value",
      "required": false
    }
  ]
}
```

## Request Body Strategies

### Full Input

Use entire input as body:

```json theme={null}
{
  "body_config": {
    "strategy": "full_input"
  }
}
```

### From Field

Extract specific field:

```json theme={null}
{
  "body_config": {
    "strategy": "from_field",
    "field": "data"
  }
}
```

### Mapped

Map multiple fields:

```json theme={null}
{
  "body_config": {
    "strategy": "mapped",
    "mappings": [
      {"to_field": "name", "from_field": "user_name"},
      {"to_field": "email", "from_field": "user_email"}
    ]
  }
}
```

## Response Handling

Control how responses are processed:

```json theme={null}
{
  "response_transform": {
    "json_path": "$.data",
    "include_metadata": false,
    "strict_status_codes": true
  }
}
```

| Option                | Effect                       |
| --------------------- | ---------------------------- |
| `json_path`           | Extract nested data          |
| `include_metadata`    | Include status code, headers |
| `strict_status_codes` | Treat non-2xx as error       |

## Example Connectors

### GitHub API

```json theme={null}
{
  "name": "github_api",
  "base_url": "https://api.github.com",
  "auth": {
    "type": "bearer",
    "token": "{github_token}"
  },
  "operations": [
    {
      "name": "get_repo",
      "method": "GET",
      "path": "/repos/{owner}/{repo}",
      "input_schema": {
        "properties": {
          "owner": {"type": "string"},
          "repo": {"type": "string"}
        }
      },
      "param_mappings": {
        "path_params": [
          {"name": "owner", "from_field": "owner"},
          {"name": "repo", "from_field": "repo"}
        ]
      }
    }
  ]
}
```

### Stripe API

```json theme={null}
{
  "name": "stripe_api",
  "base_url": "https://api.stripe.com/v1",
  "auth": {
    "type": "bearer",
    "token": "{stripe_api_key}"
  },
  "operations": [
    {
      "name": "create_charge",
      "method": "POST",
      "path": "/charges",
      "input_schema": {
        "properties": {
          "amount": {"type": "integer"},
          "currency": {"type": "string"},
          "source": {"type": "string"}
        }
      },
      "param_mappings": {
        "body_config": {
          "strategy": "mapped",
          "mappings": [
            {"to_field": "amount", "from_field": "amount"},
            {"to_field": "currency", "from_field": "currency"},
            {"to_field": "source", "from_field": "source"}
          ]
        }
      }
    }
  ]
}
```

## Common Headers

Set headers automatically on all requests:

```json theme={null}
{
  "common_headers": {
    "User-Agent": "Noorle/1.0",
    "X-Custom-Header": "value"
  }
}
```

## Rate Limits

Configure per-operation limits:

```json theme={null}
{
  "rate_limits": {
    "requests_per_minute": 60,
    "concurrent_requests": 5
  }
}
```

## Cost

For current pricing details, see [Pricing](https://noorle.com/pricing/).

Monitor in **Account** > **Usage** dashboard.

## Best Practices

### Be Specific with Parameters

Define exactly which fields are needed to reduce token usage.

### Use Appropriate HTTP Methods

* GET for retrieval
* POST for creation
* PATCH for partial updates
* DELETE for removal

### Handle Errors

Configure `strict_status_codes` to handle API errors properly.

### Validate Input

Use JSON Schema to validate required parameters.

### Document Operations

Add clear descriptions for each operation.

## Testing

Use the **Test** tab to verify operations:

1. Select operation
2. Enter sample input
3. View request and response
4. Check response format
5. Verify no errors

## Troubleshooting

### "Connection Failed"

* Verify base URL is correct
* Check network connectivity
* Ensure authentication is set up

### "Parameter Not Found"

* Verify parameter names match schema
* Check `from_field` mappings
* Ensure required parameters provided

### "Invalid Response"

* Check API documentation for response format
* Verify `json_path` is correct
* Try different response parsing options

## Next Steps

* [OpenAPI Import](/docs/run/connectors/openapi-import) - Auto-generate from spec
* [Authentication](/docs/run/connectors/authentication)
* [Parameter Mapping](/docs/run/connectors/parameter-mapping)
* [Attach to Agent](/docs/run/agents/attaching-capabilities)