Rank templates for a file

POST

/orgs/{org}/templates/fit

curl --request POST \
  --url https://api.sloose.com/orgs/org_9f3c/templates/fit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "columns": [ "example" ] }'

• Production
• Staging

How well a file fits each template the caller can see — the ones GET …/templates lists: shared with the org, and their own private ones — most fitting first, then the most recently used (lastUsedAt), then the most recently changed. A template’s fit is its recipe that fits the file best: how many of its mappings find their column in columns by the name they read, by the reader the wizard’s template check uses. It is the check’s count by name only — the check also finds a column by a name the field answers to, which needs the connection’s fields — so a template can fit better on Target than here, never worse. The import’s own Choose another template asks it, for a file that does not fit the template it was started from. Writes nothing.

Authorizations

• sessionAuth
• apiTokenAuth

Parameters

Path Parameters

org

required

The org id the session was issued for. A token for one org can never read another.

string

Example

org_9f3c

The org id the session was issued for. A token for one org can never read another.

Request Body^required

Media typeapplication/json

object

columns

required

The file’s header, as read. Past 500 columns the rest are cut, never refused — a fit is a ranking, and a file that wide is ranked on its first 500 — and a name past 500 characters is cut there.

Array<string>

Example^generated

{
  "columns": [
    "example"
  ]
}

Responses

200

Every visible template with its fit, ranked.

Media typeapplication/json

object

templates

required

Array<object>

object

id

required

string

orgId

required

string

connectorId

required

The connection it was built for, when it names one: a template saved from an import records that import’s, and an import started from it pre-selects that one. Null on a template that names none — pushed from a configuration repository, or written by an agent without one — which is picked for on Target, among the connections of its kind.

string | null

name

required

string

description

required

string | null

createdByUserId

required

string

visibility

required

string

Allowed values: private org

schemaVersion

required

number

enabledModules

required

Array<string>

libraryVersions

required

object | null

registryVersion

required

The configuration version the recipe was built against, as its save REPORTED it (#616): an agent’s save over MCP stamps the version it checked the recipe against, and a repository’s push the version it wrote (none when another write landed while it wrote the configuration, which it checks before its templates; one landing while the templates are saved is outside that check, and the stamp stays, #650); any other save, the registryVersion it sent — a label the server stores for any version the org has reached, not one it checked. null when the save said none.

number | null

sourceRef

required

bundle:<file> when pushed from a config repo; null when built by a person.

string | null

kind

required

The kind of connection this template imports into — zoho_crm. Null on a template saved before kinds were recorded, which is read as Zoho CRM, the only kind there was.

string | null

version

required

Which version of the template this is. “Update the template” writes the next one; an import that copied an earlier one is told the template has moved on.

integer

managedBy

required

sdk when a config repo owns the template: changes arrive by the next push, and updates from an import are refused. Null when people own it.

string | null

Allowed values: sdk

lastUsedAt

required

When a run last started from it — a run authorised for an import made from it, or naming it with no import, a dry run included. Null for one no run has started from. Runs are purged, so this is kept, not worked out; it moves no version.

string | null

createdAt

required

string

updatedAt

required

string

fit

required

object

found

required

Of judged, the mappings whose column the file has, by the name they read.

integer

judged

required

The mappings of the template’s best-fitting recipe that read a column the check can judge: a static value, a field left out and a formula reading columns no name says are not counted.

integer

share

required

found over judged; null when nothing could be judged, or the template’s recipe could not be read.

number | null

Example

{
  "templates": [
    {
      "visibility": "private",
      "managedBy": "sdk"
    }
  ]
}

400

The request — its body or its query — did not match the schema. issues carries the Zod issue list.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

401

No bearer, or one that is expired, revoked or no longer resolves to a member.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

403

The bearer’s role is too low, or it was issued for a different org.

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}