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

# Cactuscompute Needle fine-tuning API

The Needle API generates tool-calling training data, fine-tunes the Needle 3 model on it, and serves the resulting models for download. You draft tool definitions from a product description, generate training, validation, and test files, start a fine-tune, and download the finished model as a signed link. Files, generation jobs, fine-tunes, and API keys each have their own management operations.

## For AI agents

Draft tool definitions, generate training data, fine-tune Needle 3, and download the resulting tool-calling model as a .cact file.

## Scope

Does not handle chat completion, image generation, or model hosting for inference. Use for tool-calling data generation, Needle 3 fine-tuning, and model download only.

## Capabilities

- Draft tool definitions from a plain product description
- Generate training, validation, and test files from tool definitions
- Start a fine-tune of Needle 3 and poll its status per depth
- Download a fine-tuned model as a .cact file via a signed link
- Upload your own files and list the ones you generate
- Create and revoke API keys for your account

## Use cases

### Agent-run fine-tuning pipeline

An AI agent can take a product description, draft tool definitions from it, generate the training, validation, and test files, start a Needle 3 fine-tune, and poll the job until it succeeds. Each step is a separate call the agent chains, and the fine-tune reports evaluations per depth.

Example prompt: Draft tool definitions from a product description, generate the training files, and start a Needle 3 fine-tune

### Model download and deployment

Once a fine-tune succeeds, an agent can retrieve the model and download it as a .cact file through a short-lived signed link, ready to run on device. The models endpoint lists the base needle-3 model first, then any fine-tuned sizes.

Example prompt: List the available models, then download the latest fine-tuned model as a .cact file

### Training-data generation

A developer can draft tool definitions from a description and generate a training, validation, and test split without starting a fine-tune, using the generation job to produce data they inspect first. Draft tool definitions are limited to a set number per day.

Example prompt: Draft tool definitions and generate a training/validation/test split, then list the generated files

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/tool_schemas` | Draft tool definitions from a description |
| POST | `/generations` | Generate training, validation, and test files |
| POST | `/fine_tuning/jobs` | Start a fine-tune |
| GET | `/fine_tuning/jobs/{job_id}` | Retrieve a fine-tune's status |
| GET | `/models/{model_id}/content` | Download a model .cact file |
| POST | `/api_keys` | Create an API key |

## Key resources

- **Files** — Reserve, upload, list, retrieve, and delete files
- **Generations** — Generate training, validation, and test files from tool definitions
- **Fine-tuning** — Start, poll, cancel, and delete fine-tune jobs for Needle 3
- **Models** — List models and download a fine-tuned model as a .cact file
- **API keys** — List, create, and revoke API keys for the account

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 43 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 77 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 19 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 59 / 100
- **View full report:** https://jentic.com/apis/cactuscompute.com/cactuscompute/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Needle by hand means handling its bearer-token auth and the multi-step flow from drafting tool definitions through generation, fine-tuning, and the signed download link. Through Jentic you install once, import Needle from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** You choose which Needle operations the agent may call, such as generation and fine-tune reads, so destructive operations like deleting a model or revoking a key are not included unless you add them.
- **Credential handling:** Your Needle API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fine-tune a tool-calling model', and Jentic returns the matching Needle operation with its input schema so the agent sequences the flow without reading the docs.

## Related APIs

- **OpenAI** — OpenAI offers hosted fine-tuning of its models; Needle fine-tunes an on-device tool-calling model you download.
- **Cohere** — Cohere fine-tunes its language models in the cloud; Needle targets tool-calling and local deployment.
- **Replicate** — Replicate trains and hosts custom models for inference; Needle produces a .cact file you run yourself.
- **Hugging Face** — Hugging Face stores and distributes model artifacts; Needle generates and fine-tunes the model.

## FAQ

### What authentication does the Needle fine-tuning API use?

The Needle API authenticates with a bearer token in the Authorization header, per its OpenAPI spec. The plans endpoint is open, but creating keys, generating data, and fine-tuning all require the token.

### Is there a Needle MCP server?

You do not need an MCP server to give your agent Needle. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the generation, fine-tune, and model operations without loading another server's tool definitions into its context.

### Can I limit what my agent is allowed to do with the Needle fine-tuning API?

Yes. Write a rule that allows only the generation and fine-tune read operations, so the agent can build data and check job status but cannot delete a model or revoke a key until you add those operations, and every call it makes is logged.

### Can I download a fine-tuned model with the Needle fine-tuning API?

Yes. Once a fine-tune succeeds, the model content endpoint returns a short-lived signed link to the .cact file, so an agent can fetch the finished model and run it on device.

### What are the rate limits for the Needle fine-tuning API?

The OpenAPI spec notes that drafting tool definitions is limited per day, and fine-tunes spend a run from your plan allowance. Read the billing endpoint for your plan, limits, and usage this period.

### How do I fine-tune a model with the Needle fine-tuning API through Jentic?

Search Jentic for 'fine-tune a tool-calling model', and it returns the Needle fine-tune operation with its input schema. Draft tool definitions, generate the files, start the fine-tune, and download the result. To run it on your own infrastructure, install Jentic One from its GitHub repo.