# Connectors
## Retrieve information for all Connectors
> Returns detailed information for all registered Connectors.\
> Note that sensitive data will not be returned but information around\
> when it was updated and if its set can be found in the \`meta\` object.\
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/connectors":{"get":{"summary":"Retrieve information for all Connectors","description":"Returns detailed information for all registered Connectors.\nNote that sensitive data will not be returned but information around\nwhen it was updated and if its set can be found in the `meta` object.\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
## Add Connector
> Creates a Connector. The \`object\` various depending on the \`type\`.\
> \`passthrough\` and \`tags\` are shared amongst all types though and\
> are the mechanisms to route parts of the traffic around the Connector\
> as well as grouping and access control.\
> \
> \[Read more about Connectors here]\(
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> \
> Note: Some Connectors are not included in the documentation here as they are currently in a beta state.\
> Moreover, then some Connectors are easier to create in the web app, e.g. AWS IoT Core Connector.\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"SecretMeta":{"type":"object","properties":{"is_set":{"type":"boolean","description":"Whether the secret value is configured"},"last_updated_at":{"type":"string","format":"date-time","description":"When the secret was last updated"}},"required":["is_set","last_updated_at"]}}},"paths":{"/connectors":{"post":{"summary":"Add Connector","description":"Creates a Connector. The `object` various depending on the `type`.\n`passthrough` and `tags` are shared amongst all types though and\nare the mechanisms to route parts of the traffic around the Connector\nas well as grouping and access control.\n\n[Read more about Connectors here](https://help.onomondo.com/en/articles/213872-what-are-onomondo-connectors).\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n\nNote: Some Connectors are not included in the documentation here as they are currently in a beta state.\nMoreover, then some Connectors are easier to create in the web app, e.g. AWS IoT Core Connector.\n{% endhint %}","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"name":{"type":"string","pattern":"^[-_a-zA-Z0-9]{3,255}$","description":"A descriptive name for the connector (3-255 characters, alphanumeric, hyphens, and underscores only)"},"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The type of Connector to create"},"tags":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control (UUIDs)","nullable":true},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"}},"required":["protocol"]},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true,"description":"The port for passthrough traffic"}},"required":["protocol"]}]},"description":"Rules for routing traffic around the connector"},"options":{"type":"object","description":"Connector-specific configuration options","oneOf":[{"title":"TLS Connector Options","properties":{"host":{"type":"string","description":"The target host IP address or hostname"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The target port number"},"server_name":{"type":"string","description":"The server name for TLS SNI"},"key":{"type":"string","format":"password","description":"RSA private key in PEM format"},"ca":{"type":"string","format":"password","description":"Certificate Authority certificate in PEM format"},"cert":{"type":"string","format":"password","description":"Client certificate in PEM format"}},"required":["host","port","server_name","key","ca","cert"]},{"title":"HTTPS Connector Options","properties":{"host":{"type":"string","format":"uri","description":"The target HTTPS URL"},"shouldReturnBody":{"type":"boolean","description":"Whether to return the response body","default":false}},"required":["host"]},{"title":"AWS IoT Core Connector Options","properties":{"region":{"type":"string","description":"The AWS region for IoT Core"},"role":{"type":"string","description":"The AWS IAM role ARN for authentication"},"publishTopic":{"type":"string","description":"The MQTT topic to publish to"},"subscribeTopic":{"type":"string","description":"The MQTT topic to subscribe to"},"defaultProtocol":{"type":"string","enum":["tcp","udp"],"description":"The default protocol for connections"},"defaultPort":{"type":"integer","minimum":1,"maximum":65535,"description":"The default port for connections"}},"required":["region","role","publishTopic","subscribeTopic","defaultProtocol","defaultPort"]},{"title":"Microsoft Azure IoT Connector Options","properties":{"connectionString":{"type":"string","format":"password","description":"The Azure IoT Hub connection string"}},"required":["connectionString"]}]}}}}}},"responses":{"200":{"description":"Connector successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The Connector name"},"type":{"type":"string","enum":["tls","https","aws_iot_core","microsoft_azure_iot"],"description":"The Connector type"},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"]},"ip":{"type":"string","nullable":true}}},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"]},"ip":{"type":"string","nullable":true},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true}}}]},"description":"Passthrough rules for traffic routing"},"tags":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control"},"options":{"type":"object","description":"Connector-specific configuration (sensitive values may be omitted)"},"meta":{"type":"object","description":"Metadata about sensitive fields (only present for connectors with secrets)","properties":{"ca":{"$ref":"#/components/schemas/SecretMeta"},"key":{"$ref":"#/components/schemas/SecretMeta"},"cert":{"$ref":"#/components/schemas/SecretMeta"},"connectionString":{"$ref":"#/components/schemas/SecretMeta"}}}}}}}}}}}}}
```
## Update Connector
> Use a PATCH request to update an Onomondo Connector in your account.\
> \
> \
> Update one of the settings of your Connector:\
> \- \`name\`: Change the name\
> \- \`type\`: Change the type of the Connector. For this to be successful, you will need to also update the \`options\` field with the new Connector type details.\
> \- \`passthrough\`: An array of objects to exclude being processed up by the connector. Each object requires at least a "protocol" (of either \`udp\`,\`tcp\`, or \`icmp\`).\
> \- \`tags\`: An array of Tag IDs to be associated with a Connector.\
> \- \`options\`: See the \`POST\` requests for each of the Connectors for fields required in the options field.\
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"SecretMeta":{"type":"object","properties":{"is_set":{"type":"boolean","description":"Whether the secret value is configured"},"last_updated_at":{"type":"string","format":"date-time","description":"When the secret was last updated"}},"required":["is_set","last_updated_at"]}}},"paths":{"/connectors/{connector_name}":{"patch":{"summary":"Update Connector","description":"Use a PATCH request to update an Onomondo Connector in your account.\n\n\nUpdate one of the settings of your Connector:\n- `name`: Change the name\n- `type`: Change the type of the Connector. For this to be successful, you will need to also update the `options` field with the new Connector type details.\n- `passthrough`: An array of objects to exclude being processed up by the connector. Each object requires at least a \"protocol\" (of either `udp`,`tcp`, or `icmp`).\n- `tags`: An array of Tag IDs to be associated with a Connector.\n- `options`: See the `POST` requests for each of the Connectors for fields required in the options field.\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","operationId":"updateConnector","tags":["Connectors"],"parameters":[{"name":"connector_name","in":"path","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The type of Connector (must update options field when changing type)"},"tags":{"type":"array","items":{"type":"string"},"description":"An array of Tag IDs to be associated with a SIM. Tag IDs require string format and can be obtained using GET /tags endpoint. **Caution**: Include all Tags you want to keep plus any new ones, as this replaces the entire list of Tags."},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"}},"required":["protocol"]},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"],"description":"The protocol for passthrough traffic"},"ip":{"type":"string","nullable":true,"description":"The IP address for passthrough traffic"},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true,"description":"The port for passthrough traffic"}},"required":["protocol"]}]},"description":"Rules for routing traffic around the connector"},"options":{"type":"object","description":"Connector-specific configuration options (see POST examples for each connector type)","oneOf":[{"title":"TLS Connector Options","properties":{"host":{"type":"string","description":"The target host IP address or hostname"},"port":{"type":"integer","minimum":1,"maximum":65535,"description":"The target port number"},"server_name":{"type":"string","description":"The server name for TLS SNI"},"key":{"type":"string","format":"password","description":"RSA private key in PEM format"},"ca":{"type":"string","format":"password","description":"Certificate Authority certificate in PEM format"},"cert":{"type":"string","format":"password","description":"Client certificate in PEM format"}}},{"title":"HTTPS Connector Options","properties":{"host":{"type":"string","format":"uri","description":"The target HTTPS URL"},"shouldReturnBody":{"type":"boolean","description":"Whether to return the response body"}}},{"title":"AWS IoT Core Connector Options","properties":{"region":{"type":"string","description":"The AWS region for IoT Core"},"role":{"type":"string","description":"The AWS IAM role ARN for authentication"},"publishTopic":{"type":"string","description":"The MQTT topic to publish to"},"subscribeTopic":{"type":"string","description":"The MQTT topic to subscribe to"},"defaultProtocol":{"type":"string","enum":["tcp","udp"],"description":"The default protocol for connections"},"defaultPort":{"type":"integer","minimum":1,"maximum":65535,"description":"The default port for connections"}}},{"title":"Microsoft Azure IoT Connector Options","properties":{"connectionString":{"type":"string","format":"password","description":"The Azure IoT Hub connection string"}}}]}}}}}},"responses":{"200":{"description":"Connector successfully updated","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The Connector name"},"type":{"type":"string","enum":["https","tls","microsoft_azure_iot","aws_iot_core"],"description":"The connector type"},"passthrough":{"type":"array","nullable":true,"items":{"oneOf":[{"type":"object","properties":{"protocol":{"type":"string","enum":["icmp"]},"ip":{"type":"string","nullable":true}}},{"type":"object","properties":{"protocol":{"type":"string","enum":["tcp","udp"]},"ip":{"type":"string","nullable":true},"port":{"type":"integer","minimum":0,"maximum":65535,"nullable":true}}}]},"description":"Passthrough rules for traffic routing"},"tags":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"Tags for grouping and access control"},"options":{"type":"object","description":"Connector-specific configuration (sensitive values may be omitted)"},"meta":{"type":"object","description":"Metadata about sensitive fields (only present for connectors with secrets)","properties":{"ca":{"$ref":"#/components/schemas/SecretMeta"},"key":{"$ref":"#/components/schemas/SecretMeta"},"cert":{"$ref":"#/components/schemas/SecretMeta"},"connectionString":{"$ref":"#/components/schemas/SecretMeta"}}}}}}}}}}}}}
```
## Remove Connector
> Removes a specific Connector.\
> \
> \
> Note that all mappings to said Connector will need to be\
> removed prior to the removal of the Connector itself, otherwise\
> a \`403\` status code will be encountered.\
> \
> \
> {% hint style="info" %}\
> Minimum package requirement: \Enterprise\\
> {% endhint %}
```json
{"openapi":"3.0.0","info":{"title":"Onomondo's API","version":"1.0.0"},"servers":[{"url":"https://api.onomondo.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization"}}},"paths":{"/connectors/{connector_name}":{"delete":{"summary":"Remove Connector","description":"Removes a specific Connector.\n\n\nNote that all mappings to said Connector will need to be\nremoved prior to the removal of the Connector itself, otherwise\na `403` status code will be encountered.\n\n\n{% hint style=\"info\" %}\nMinimum package requirement: Enterprise\n{% endhint %}","parameters":[{"name":"connector_name","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Connector still mapped to some SIMs","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.onomondo.com/readme/connectors.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.