# Templates

## List templates

> Returns all templates owned by the authenticated Partner account.\
> \
> The response is a flat JSON array — there is no pagination.\
> \
> \*\*Partner-only endpoint.\*\*

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Template":{"type":"object","description":"A template resource as returned by the API.\n\nFields that are `false` or empty may be omitted from the response\n(e.g. `published` is omitted when the template is unpublished,\n`imageURL` is omitted when not set).","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the template.","readOnly":true},"name":{"type":"string","description":"Display name of the template."},"description":{"type":"string","description":"Longer description shown in the marketplace."},"imageURL":{"type":"string","format":"uri","description":"URL of the template's marketplace image. Omitted when not set."},"websiteURL":{"type":"string","format":"uri","description":"URL to the partner's website or template landing page."},"contactEmail":{"type":"string","format":"email","description":"Contact email for template support."},"published":{"type":"boolean","description":"Whether the template is published to the marketplace.\nOmitted from the response when `false`. Cannot be set to\n`true` until a template zip file has been uploaded.","readOnly":true},"lastModified":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the last modification. Server-managed.","readOnly":true},"applications":{"type":"array","items":{"type":"string"},"description":"Application identifiers associated with this template.\nValues may be application slugs (e.g. `salesforce`,\n`integratorio`) or Mongo ObjectIds."},"free":{"type":"boolean","description":"Whether the template is free to install. Server-managed, read-only.","readOnly":true},"numInstalls":{"type":"integer","description":"Number of times this template has been installed. Server-managed, read-only.","readOnly":true}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/templates":{"get":{"operationId":"listTemplates","tags":["Templates"],"summary":"List templates","description":"Returns all templates owned by the authenticated Partner account.\n\nThe response is a flat JSON array — there is no pagination.\n\n**Partner-only endpoint.**","responses":{"200":{"description":"Array of template resources.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Create a template

> Creates a new integration template.\
> \
> The \`name\` field is required. The server auto-generates \`\_id\`,\
> \`lastModified\`, \`applications\`, \`free\`, and \`numInstalls\`.\
> \
> The \`published\` and \`free\` fields are read-only and cannot be set\
> via POST or PUT.\
> \
> \*\*Partner-only endpoint.\*\*

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"TemplateInput":{"type":"object","description":"Request body for creating or updating a template.","required":["name"],"properties":{"name":{"type":"string","description":"Display name of the template."},"description":{"type":"string","description":"Longer description shown in the marketplace."},"imageURL":{"type":"string","format":"uri","description":"URL of the template's marketplace image."},"websiteURL":{"type":"string","format":"uri","description":"URL to the partner's website or template landing page."},"contactEmail":{"type":"string","format":"email","description":"Contact email for template support."},"applications":{"type":"array","items":{"type":"string"},"description":"Application identifiers to associate with this template.\nValues may be application slugs (e.g. `salesforce`,\n`integratorio`) or Mongo ObjectIds."}}},"Template":{"type":"object","description":"A template resource as returned by the API.\n\nFields that are `false` or empty may be omitted from the response\n(e.g. `published` is omitted when the template is unpublished,\n`imageURL` is omitted when not set).","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the template.","readOnly":true},"name":{"type":"string","description":"Display name of the template."},"description":{"type":"string","description":"Longer description shown in the marketplace."},"imageURL":{"type":"string","format":"uri","description":"URL of the template's marketplace image. Omitted when not set."},"websiteURL":{"type":"string","format":"uri","description":"URL to the partner's website or template landing page."},"contactEmail":{"type":"string","format":"email","description":"Contact email for template support."},"published":{"type":"boolean","description":"Whether the template is published to the marketplace.\nOmitted from the response when `false`. Cannot be set to\n`true` until a template zip file has been uploaded.","readOnly":true},"lastModified":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the last modification. Server-managed.","readOnly":true},"applications":{"type":"array","items":{"type":"string"},"description":"Application identifiers associated with this template.\nValues may be application slugs (e.g. `salesforce`,\n`integratorio`) or Mongo ObjectIds."},"free":{"type":"boolean","description":"Whether the template is free to install. Server-managed, read-only.","readOnly":true},"numInstalls":{"type":"integer","description":"Number of times this template has been installed. Server-managed, read-only.","readOnly":true}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/templates":{"post":{"operationId":"createTemplate","tags":["Templates"],"summary":"Create a template","description":"Creates a new integration template.\n\nThe `name` field is required. The server auto-generates `_id`,\n`lastModified`, `applications`, `free`, and `numInstalls`.\n\nThe `published` and `free` fields are read-only and cannot be set\nvia POST or PUT.\n\n**Partner-only endpoint.**","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateInput"}}}},"responses":{"201":{"description":"Template created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## Get a template

> Returns a single template by ID.\
> \
> \*\*Partner-only endpoint.\*\*

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Template":{"type":"object","description":"A template resource as returned by the API.\n\nFields that are `false` or empty may be omitted from the response\n(e.g. `published` is omitted when the template is unpublished,\n`imageURL` is omitted when not set).","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the template.","readOnly":true},"name":{"type":"string","description":"Display name of the template."},"description":{"type":"string","description":"Longer description shown in the marketplace."},"imageURL":{"type":"string","format":"uri","description":"URL of the template's marketplace image. Omitted when not set."},"websiteURL":{"type":"string","format":"uri","description":"URL to the partner's website or template landing page."},"contactEmail":{"type":"string","format":"email","description":"Contact email for template support."},"published":{"type":"boolean","description":"Whether the template is published to the marketplace.\nOmitted from the response when `false`. Cannot be set to\n`true` until a template zip file has been uploaded.","readOnly":true},"lastModified":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the last modification. Server-managed.","readOnly":true},"applications":{"type":"array","items":{"type":"string"},"description":"Application identifiers associated with this template.\nValues may be application slugs (e.g. `salesforce`,\n`integratorio`) or Mongo ObjectIds."},"free":{"type":"boolean","description":"Whether the template is free to install. Server-managed, read-only.","readOnly":true},"numInstalls":{"type":"integer","description":"Number of times this template has been installed. Server-managed, read-only.","readOnly":true}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/templates/{_id}":{"get":{"operationId":"getTemplateById","tags":["Templates"],"summary":"Get a template","description":"Returns a single template by ID.\n\n**Partner-only endpoint.**","parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template ID."}],"responses":{"200":{"description":"The template resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Update a template

> Updates a template resource. Only the fields included in the\
> request body are changed; omitted fields retain their current\
> values.\
> \
> The \`name\` field is required in the request body.\
> \
> The \`published\` field cannot be set to \`true\` until a template\
> zip file has been uploaded.\
> \
> \*\*Partner-only endpoint.\*\*

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"TemplateInput":{"type":"object","description":"Request body for creating or updating a template.","required":["name"],"properties":{"name":{"type":"string","description":"Display name of the template."},"description":{"type":"string","description":"Longer description shown in the marketplace."},"imageURL":{"type":"string","format":"uri","description":"URL of the template's marketplace image."},"websiteURL":{"type":"string","format":"uri","description":"URL to the partner's website or template landing page."},"contactEmail":{"type":"string","format":"email","description":"Contact email for template support."},"applications":{"type":"array","items":{"type":"string"},"description":"Application identifiers to associate with this template.\nValues may be application slugs (e.g. `salesforce`,\n`integratorio`) or Mongo ObjectIds."}}},"Template":{"type":"object","description":"A template resource as returned by the API.\n\nFields that are `false` or empty may be omitted from the response\n(e.g. `published` is omitted when the template is unpublished,\n`imageURL` is omitted when not set).","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the template.","readOnly":true},"name":{"type":"string","description":"Display name of the template."},"description":{"type":"string","description":"Longer description shown in the marketplace."},"imageURL":{"type":"string","format":"uri","description":"URL of the template's marketplace image. Omitted when not set."},"websiteURL":{"type":"string","format":"uri","description":"URL to the partner's website or template landing page."},"contactEmail":{"type":"string","format":"email","description":"Contact email for template support."},"published":{"type":"boolean","description":"Whether the template is published to the marketplace.\nOmitted from the response when `false`. Cannot be set to\n`true` until a template zip file has been uploaded.","readOnly":true},"lastModified":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the last modification. Server-managed.","readOnly":true},"applications":{"type":"array","items":{"type":"string"},"description":"Application identifiers associated with this template.\nValues may be application slugs (e.g. `salesforce`,\n`integratorio`) or Mongo ObjectIds."},"free":{"type":"boolean","description":"Whether the template is free to install. Server-managed, read-only.","readOnly":true},"numInstalls":{"type":"integer","description":"Number of times this template has been installed. Server-managed, read-only.","readOnly":true}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/templates/{_id}":{"put":{"operationId":"updateTemplate","tags":["Templates"],"summary":"Update a template","description":"Updates a template resource. Only the fields included in the\nrequest body are changed; omitted fields retain their current\nvalues.\n\nThe `name` field is required in the request body.\n\nThe `published` field cannot be set to `true` until a template\nzip file has been uploaded.\n\n**Partner-only endpoint.**","parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateInput"}}}},"responses":{"200":{"description":"Updated template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## Delete a template

> Deletes a template.\
> \
> \*\*Partner-only endpoint.\*\*

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/templates/{_id}":{"delete":{"operationId":"deleteTemplate","tags":["Templates"],"summary":"Delete a template","description":"Deletes a template.\n\n**Partner-only endpoint.**","parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string"},"description":"The template ID."}],"responses":{"204":{"description":"Template deleted."},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Install an integration from a template

> Installs an integration from a published template. The caller provides a\
> \`connectionMap\` that maps each template-defined connection ID to an actual\
> connection ID in the caller's account.\
> \
> AI guidance:\
> \- Use \`GET /v1/templates/{\_id}/preview\` (marketplace spec) first to\
>   discover the connection IDs the template expects — they appear as\
>   \`\_id\` values on \`model: "Connection"\` entries in the preview response.\
> \- Every template connection must appear as a key in \`connectionMap\`;\
>   missing or empty map → \*\*400 \`invalid\_connectionMap\`\*\*.\
> \- If the keys don't match the template's connection IDs, the server\
>   returns \*\*422 \`invalid\_connectionId\`\*\* and the error message reveals\
>   which connection IDs are expected.\
> \- A bogus template \`\_id\` → \*\*404 \`invalid\_ref\` "Template not found."\*\*.

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/integrations/template/{_id}":{"post":{"operationId":"installTemplate","tags":["Templates"],"summary":"Install an integration from a template","description":"Installs an integration from a published template. The caller provides a\n`connectionMap` that maps each template-defined connection ID to an actual\nconnection ID in the caller's account.\n\nAI guidance:\n- Use `GET /v1/templates/{_id}/preview` (marketplace spec) first to\n  discover the connection IDs the template expects — they appear as\n  `_id` values on `model: \"Connection\"` entries in the preview response.\n- Every template connection must appear as a key in `connectionMap`;\n  missing or empty map → **400 `invalid_connectionMap`**.\n- If the keys don't match the template's connection IDs, the server\n  returns **422 `invalid_connectionId`** and the error message reveals\n  which connection IDs are expected.\n- A bogus template `_id` → **404 `invalid_ref` \"Template not found.\"**.","parameters":[{"name":"_id","in":"path","required":true,"description":"The template ID to install from.","schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Connection mapping from template connection IDs to the caller's\nreal connection IDs.","properties":{"connectionMap":{"type":"object","description":"Keys are connection `_id` values from the template; values are\nthe caller's own connection `_id` values that should replace\nthem during install.","additionalProperties":{"type":"string"}}},"required":["connectionMap"]}}}},"responses":{"200":{"description":"Template installed successfully.","content":{"application/json":{"schema":{"type":"object","description":"The created integration and related resources.","additionalProperties":true}}}},"400":{"description":"Missing or empty `connectionMap`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"Template not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Connection IDs in `connectionMap` do not match the template's\nexpected connection IDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Preview a template install from an uploaded zip

> Previews the resources that would be created by installing a template\
> from an uploaded zip file. The \`runKey\` query parameter ties this request\
> to a previously uploaded zip (obtained from \`GET /v1/s3SignedURL\`).\
> \
> AI guidance:\
> \- The \`runKey\` is returned by \`GET /v1/s3SignedURL\` after the zip has\
>   been uploaded to the signed URL.\
> \- Missing \`runKey\` → \*\*400 \`missing\_required\_field\`\*\*.\
> \- If \`runKey\` doesn't match any uploaded zip → \*\*404 \`invalid\_key\`\*\*.

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/integrations/template/preview":{"get":{"operationId":"previewTemplateInstall","tags":["Templates"],"summary":"Preview a template install from an uploaded zip","description":"Previews the resources that would be created by installing a template\nfrom an uploaded zip file. The `runKey` query parameter ties this request\nto a previously uploaded zip (obtained from `GET /v1/s3SignedURL`).\n\nAI guidance:\n- The `runKey` is returned by `GET /v1/s3SignedURL` after the zip has\n  been uploaded to the signed URL.\n- Missing `runKey` → **400 `missing_required_field`**.\n- If `runKey` doesn't match any uploaded zip → **404 `invalid_key`**.","parameters":[{"name":"runKey","in":"query","required":true,"description":"The `runKey` returned by `GET /v1/s3SignedURL` after uploading the\ntemplate zip file.","schema":{"type":"string"}}],"responses":{"200":{"description":"Preview of resources the template would create.","content":{"application/json":{"schema":{"type":"object","description":"Preview envelope with resource docs.","additionalProperties":true}}}},"400":{"description":"Missing required `runKey` query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"The `runKey` does not match any uploaded zip.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Install a template from an uploaded zip

> Installs a template from a previously uploaded zip file. The \`runKey\`\
> in the request body ties this request to the zip upload (obtained from\
> \`GET /v1/s3SignedURL\`).\
> \
> AI guidance:\
> \- First upload a template zip to the signed URL from \`GET /v1/s3SignedURL\`,\
>   then use \`GET /v1/integrations/template/preview?runKey=...\` to preview,\
>   and finally POST here to install.\
> \- Missing \`runKey\` → \*\*400\*\*.\
> \- If \`runKey\` doesn't match any uploaded zip → \*\*404 \`invalid\_key\`\*\*.

```json
{"openapi":"3.1.0","info":{"title":"Templates","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/integrations/template":{"post":{"operationId":"installTemplateFromZip","tags":["Templates"],"summary":"Install a template from an uploaded zip","description":"Installs a template from a previously uploaded zip file. The `runKey`\nin the request body ties this request to the zip upload (obtained from\n`GET /v1/s3SignedURL`).\n\nAI guidance:\n- First upload a template zip to the signed URL from `GET /v1/s3SignedURL`,\n  then use `GET /v1/integrations/template/preview?runKey=...` to preview,\n  and finally POST here to install.\n- Missing `runKey` → **400**.\n- If `runKey` doesn't match any uploaded zip → **404 `invalid_key`**.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The `runKey` from the zip upload.","properties":{"runKey":{"type":"string","description":"The `runKey` returned by `GET /v1/s3SignedURL` after uploading\nthe template zip file."}},"required":["runKey"]}}}},"responses":{"200":{"description":"Template installed from uploaded zip.","content":{"application/json":{"schema":{"type":"object","description":"The created integration and related resources.","additionalProperties":true}}}},"400":{"description":"Missing required `runKey` in request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"The `runKey` does not match any uploaded zip.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# 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://developer.celigo.com/api/api-reference/templates.md?ask=<question>
```

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.