canonical: https://jentic.com/apis/nyckel.com/nyckel

# Nyckel Classification API

The Nyckel API powers a no-code machine-learning classification platform that supports text, image, and tabular inputs. The 25-endpoint surface lets developers create classification functions, define labels and fields, upload training samples, and invoke trained functions for inference. It is designed for developers who need image moderation, text categorisation, or structured-data classification without building and operating their own ML pipeline, and it ships with built-in model selection and retraining behind the scenes.

## For AI agents

Create classification functions, manage labels and training samples, and invoke trained models for text, image, and tabular classification with bearer authentication.

## Scope

Does not handle generative text or image creation, embeddings, or speech transcription - use for supervised classification only.

## Capabilities

- List and inspect existing classification functions in your Nyckel workspace
- Define classification labels and structured fields for a function
- Upload labelled training samples to teach a classification function
- Invoke a trained function to classify a new text, image, or tabular input
- Delete classification functions, labels, or fields when retiring a workflow
- Exchange client credentials for a short-lived access token via `/connect/token`

## Use cases

### Content Moderation Pipeline

Build an image or text moderation step into a user-generated-content pipeline by training a Nyckel function on labelled examples and invoking it on every upload. The training-and-inference loop runs entirely through the API, so a developer can iterate on the labelset without leaving the codebase. Time to a live classifier is typically under a day from a labelled dataset of a few hundred examples.

Example prompt: POST a labelled training sample to `/v1/functions/{functionId}/samples` for each image, then call POST `/v1/functions/{functionId}/invoke` with new uploads to score them.

### Support Ticket Triage

Auto-route inbound support tickets by training a text classifier on past tickets labelled with their handling team. Once trained, the function is invoked on each new ticket to predict the routing label, which can be written back to a CRM or helpdesk. Nyckel's managed model selection means there is no separate training infrastructure to operate.

Example prompt: Invoke `/v1/functions/{functionId}/invoke` with the ticket subject and body, then patch the ticket in the helpdesk with the predicted routing label.

### Tabular Lead Scoring

Score inbound leads by training a tabular classification function with fields such as company size, industry, and channel, mapped to historic outcomes. The fields endpoints let you define the input schema, and the invoke endpoint returns the predicted label with a confidence score. This works well as an alternative to bespoke ML services for teams without a data-science function.

Example prompt: POST `/v1/functions/{functionId}/fields` to define the lead schema, then POST `/v1/functions/{functionId}/invoke` with a new lead's fields and read the predicted label.

### Agent-Driven Classification

Let an AI agent decide which Nyckel function to invoke for an incoming item - for example sending images to a moderation function and text to a sentiment function - by listing the available functions and routing accordingly. Through Jentic, the agent searches by intent and gets only the operations it needs, with credentials handled by the platform.

Example prompt: Search Jentic for 'invoke a Nyckel classification function', load the operation, and call the correct function id for the incoming item.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/connect/token` | Exchange client credentials for an access token |
| GET | `/v1/functions` | List classification functions |
| GET | `/v1/functions/{functionId}` | Get a function by ID |
| POST | `/v1/functions/{functionId}/invoke` | Invoke a classification function |
| POST | `/v1/functions/{functionId}/fields` | Create a field for a function |

## Key resources

- **Functions** — Classification functions - create, list, retrieve, delete.
- **Labels** — Output classes attached to a function.
- **Fields** — Input schema for tabular classification functions.
- **Samples** — Labelled training data uploaded to a function.
- **Invocation** — Inference endpoint that returns predicted label and confidence.
- **Token** — Client-credentials exchange that returns a short-lived bearer token.

## Why Jentic

- **Setup:** Wiring Nyckel by hand means running the `/connect/token` client-credentials exchange, managing the JWT bearer token against www.nyckel.com, and handling the request plumbing yourself. Through Jentic you install once, import Nyckel from the API Directory, store the client id and secret once, and your agent calls it.
- **Permission scoping:** Nyckel puts the function id in the URL path (`/v1/functions/{functionId}/...`), so a rule can pin your agent to one classifier: it can invoke that function and read its fields and nothing else. You choose the operations it may call, so adding training samples or fields is not included unless you add it.
- **Credential handling:** Your Nyckel client id and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time, and Jentic handles the `/connect/token` exchange. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'invoke a Nyckel classifier' or 'list Nyckel functions', and Jentic returns the matching Nyckel operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Clarifai API** — Computer-vision-first classification and detection platform with prebuilt models - strongest alternative for image workloads.
- **Hugging Face Inference API** — Serverless inference against open-source classification models hosted on the Hub.
- **OpenAI API** — Pair with Nyckel - use a chat model for prompt-based extraction and Nyckel for fast, cheap structured classification.

## FAQ

### What authentication does the Nyckel API use?

The API uses bearer tokens issued via the OAuth2 client-credentials flow at POST `/connect/token.` You exchange a client id and client secret for a short-lived access token, then send it in the Authorization header. Through Jentic, the client id and secret are stored encrypted in the vault and the token exchange is handled automatically.

### Can I train a classifier through the API?

Yes - create a function, define its labels (and fields for tabular use cases), then post labelled training samples to `/v1/functions/{functionId}/samples.` Nyckel manages model selection and retraining once samples are uploaded.

### What are the rate limits for the Nyckel API?

The OpenAPI spec does not embed explicit limits. Nyckel's published policy throttles per-account based on plan; back off on HTTP 429 and consider batching invocations where the integration permits.

### How do I invoke a classifier through Jentic?

Run pip install jentic, then search for 'invoke a Nyckel classification function'. Jentic returns POST `/v1/functions/{functionId}/invoke` with its input schema; supply the function id and input data and execute. Run it through Jentic One, the self-hosted execution layer, to get an agent API key.

### Does Nyckel support image inputs?

Yes - classification functions support text, image, and tabular inputs depending on how the function is configured. The same `/v1/functions/{functionId}/invoke` endpoint handles all three modalities, with the request body adapted to the input type.

### Can I limit what my agent is allowed to do with the Nyckel Classification API?

Yes. Because Nyckel puts the function id in the URL path, such as `/v1/functions/{functionId}/invoke`, a rule in your self-hosted Jentic One can pin your agent to a single classifier so it can invoke that function and read its fields and nothing else. You decide which operations the agent may call, so posting training samples to `/v1/functions/{functionId}/samples` or creating fields is excluded unless you explicitly allow it. Your Nyckel client id and secret stay under your control and are injected only for the operations you permit.