Get Started

Paste one prompt into your agent and you are set up. Pick the path that matches what you are building.

Quick start

Connect an agent (MCP)

For an assistant such as Claude, ChatGPT, Cursor, or Codex that you talk to about your farm. The agent connects to the Print Hive MCP server and you sign in with OAuth. No API key is needed.

Help me connect Print Hive (https://www.printhiv3d.com) to this assistant so you can answer questions about my 3D print farm.

Read the current setup guide at https://www.printhiv3d.com/docs/mcp first. Use the instructions for this client and preserve any existing MCP servers or configuration.

The Print Hive Streamable HTTP MCP endpoint is https://api.printhiv3d.com/v1/mcp. Guide me through adding Print Hive and completing its OAuth sign-in. Do not add an API key or x-api-key header. I need a Print Hive account with access to an organization; if I don't have one, help me get started at https://app.printhiv3d.com/signup. Let me complete sign-in, organization selection, and authorization myself. Never ask me to paste tokens, API keys, claim codes, or printer access codes into chat.

If this client cannot configure a connection directly, show me the manual steps from the client guide. Do not claim the connection succeeded until a read-only Print Hive tool call has verified it.

After connecting, list my printers, separating connectivity from print activity, and tell me what to do next on the farm. Do not start, stop, heat, or move a printer to test the connection.

Client-specific steps are in the MCP docs.

Build an integration (REST SDK)

For an app, script, or backend service that calls Print Hive on its own. The agent installs @printhive/api, adds a note to AGENTS.md so later sessions keep the context, and verifies your API key with a read-only call.

Set up the Print Hive REST API (https://www.printhiv3d.com) in this project so my code can list my printers and queue print jobs.

Read https://www.printhiv3d.com/docs/api/get-started first, then follow these steps:

1. Install @printhive/api with the project's package manager. It needs Node.js 20 or newer. If a release-age or install policy blocks it, stop and ask me instead of changing the policy.

2. Add this note to AGENTS.md, creating the file if needed: "Print Hive: use the @printhive/api SDK. Before you use it, read node_modules/@printhive/api/llms.txt (the quickstart is node_modules/@printhive/api/README.md). Read https://www.printhiv3d.com/docs/api/get-started for setup, scopes, and error codes. The key is in PRINTHIVE_API_KEY and is sent as the x-api-key header. Never log it, commit it, or ship it to a browser. Ask me before you call printJobs.start."

3. I need an organization API key. Tell me to create one in Print Hive under Settings > API Keys (https://app.printhiv3d.com) with the read scope to list, or control to also queue jobs, and to put it in PRINTHIVE_API_KEY. If my code needs live updates, also tell me what to tick under Live events: Printers for printers.watch(), Print jobs for events.subscribe({ kinds: ["job.*"] }), or both boxes for both. All event kinds is only for code that needs every kind. Never ask me to paste the key into chat.

4. Verify the key with one read-only call: new PrintHive({ apiKey: process.env.PRINTHIVE_API_KEY }).printers.list({ limit: 50 }). An empty list is normal for a new organization: printers appear after HiveLink is installed and connected. Do not claim setup worked until this call returns.

Do not start, stop, heat, or move a printer to test the setup. Ask me which printer and file to use before you queue a job.

Which one?

MCPREST SDK
Best forAssistants a person talks toApps, scripts, and services
Sign-inOAuth in the clientOrganization API key
SurfaceFarm tools, with approval-gated actionsPublic endpoints and the typed SDK

Before you start

  • A Print Hive account and organization. Sign up at app.printhiv3d.com.
  • To see or print on printers: HiveLink running on your network with at least one printer connected. See Getting Started. Until then, printer lists are empty and job requests fail with no_qualified_target_model.

Create an API key

  1. In Print Hive, open Settings → API Keys.
  2. Choose the smallest scope your integration needs (see below).
  3. Copy the key. Print Hive shows it only once. Store it in an environment variable such as PRINTHIVE_API_KEY.

Send the key in the x-api-key header. Never put it in a query string, client-side code, or a chat with an agent.

ScopeAllows
readRead printers, jobs, queue, models, and files.
controlEverything in read, plus create, release, start, and cancel queued print jobs.
dangerousEverything in control, plus operations that act on a running print, such as stop. Only an organization owner or admin can grant it.
events:read:printer, events:read:job, events:readThe live stream. Under Live events, choose Printers, Print jobs, or All event kinds. See Watch printers live.

Live events is a section of the Create API Key form. In the web app you cannot add it to an existing key, because Change access covers only MCP tool access and webhooks. Create a new key instead.

Each endpoint in the reference lists the scope it needs. OAuth tokens issued to MCP clients work only on the MCP server; REST endpoints answer them with 403.

Make your first call

curl https://api.printhiv3d.com/v1/printers \
  -H "x-api-key: $PRINTHIVE_API_KEY"

Or with the SDK (Node.js 20 or newer):

npm install @printhive/api
import { PrintHive } from "@printhive/api";

const apiKey = process.env.PRINTHIVE_API_KEY;
if (!apiKey) throw new Error("Set PRINTHIVE_API_KEY");
const hive = new PrintHive({ apiKey });
const { printers } = await hive.printers.list({ limit: 50 }); // typed: printers[0].id is a string

A new organization returns {"printers":[],"nextCursor":null}. GET /v1/api-keys lists every key in the organization with its name, scopes, and expiry. Find yours by the name you gave it.

Queue a print job

You need a .3mf project file. To try the flow, download this sample cube (one PETG plate). Creating a job needs the control scope.

// Ask the person first: a created job can print as soon as its printer is ready.
// The printer the person approves, or undefined to leave it to Smart Queue.
const approvedPrinterId = printers[0]?.id;
const request = await hive.printJobs.create({
  file: "./cube.3mf",
  filename: "cube.3mf",
  plate: 1,
  filaments: [{ sourceSlot: 0, material: "PETG", color: "#39FF14" }],
  printer_id: approvedPrinterId, // omit to leave it to Smart Queue
  idempotencyKey: "order-1042-plate-1", // one per job; reuse only to retry it
});

// Hive prepares the file in the background.
const created = await hive.printJobs.waitUntilCreated(request.requestId);

// To abandon a request that has not become a job yet:
// await hive.printJobs.cancelCreateRequest(request.requestId);
// To hold the job until the person approves, create it with release: "manual".
// waitUntilCreated then throws with the held request; see the SDK's
// docs/reference.md, "Release or cancel a creation request".

create returns a request at once and Print Hive prepares the job in the background. A request that fails stays failed with an error code (see below). Sending the same idempotencyKey again returns the same request, so retries are safe.

To start a queued job, call hive.printJobs.start. It sends POST /v1/print-jobs/{id}/start and needs the control scope. Take the job id from the created request's job.id, and pass the printer the person approved before create. If the job is reassigned, expectedPrinterId (expected_printer_id over REST) makes the call fail instead of starting the print on another printer.

const job = created.job;
if (!job) throw new Error("The job no longer exists");
// With Smart Queue routing, ask the person again before you prioritize the job.
if (!approvedPrinterId) throw new Error("No printer was approved for this job");

// Optional: move it to the front of the approved printer's queue now.
const started = await hive.printJobs.start(job.id, {
  expectedPrinterId: approvedPrinterId, // fail instead of printing on another printer
});
console.log(started.dispatch); // "requested": the job stays QUEUED until HiveLink claims it

The same call over REST:

curl -X POST https://api.printhiv3d.com/v1/print-jobs/48213/start \
  -H "x-api-key: $PRINTHIVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"expected_printer_id":"7d3f1c2a-5b8e-4f6a-9c1d-2e4b6a8c0f13"}'

A 200 means dispatch was requested. The job stays QUEUED until HiveLink claims it on its next poll. A 409 names the failed check in reason, such as printer_busy, printer_not_ready, or job_unassigned. The SDK throws PrintHiveApiError with that reason in error.body. Starting a print uses a real printer and filament. A created job can print without start once its printer is ready, so an agent must ask the user before it creates a job.

Watch printers live

hive.printers.watch() streams each printer's status, progress, temperatures, and filament. It first sends each printer's latest stored sample, if it is at most 24 hours old. After that, an online printer typically sends a sample at least every 60 seconds, and a Bambu printer about every 10 seconds while it prints. The client reconnects on its own.

// The key needs events:read:printer or events:read.
const watch = hive.printers.watch();
for await (const update of watch) {
  if (update.type === "connection") {
    console.log("stream", update.state); // "connected" or "reconnecting"
    continue;
  }
  if (update.type !== "printer") continue;
  const { printerName, stage, progress } = update.printer;
  console.log(printerName, stage.phase, progress.percent, progress.remainingMinutes);
}

A connection item says connected once Pulse accepts the subscription, and reconnecting while the client retries. Only a printer item confirms that telemetry arrived, so a quiet loop after connected does not prove that no printer is reporting.

For job events, use hive.events.subscribe with a key that holds events:read:job. Save its cursor after you handle each durable event, and pass the cursor back as since when your process restarts. If the stream sends a reset item, read the current state with REST, save the item's head as your cursor, then keep reading. The stream is a Socket.IO connection to pulse.printhiv3d.com, so keep the key on your server. Pulse refuses Host keys, keys bound to a Host, keys with a production:* scope, and keys with the legacy * scope.

Errors

Errors return JSON with error and message. Some add a machine-readable code. A missing scope returns:

{"error":"Forbidden","code":"API_KEY_SCOPE_REQUIRED","message":"API key scope \"dangerous\" is required"}

A failed creation request carries its code in the request's error object, as error.error beside error.statusCode. The two Request failed codes below also carry error.message, which says what to do. The ones you are most likely to hit first:

StatusCodeMeaning
401UnauthorizedThe x-api-key header is missing, or the key is invalid, disabled, or expired. An endpoint that accepts only a signed-in session also answers 401 to an API key. GET /v1/organizations is one, and its message says that API keys are not accepted.
403API_KEY_SCOPE_REQUIREDThe key lacks a scope. The message names the scope, for example API key scope "dangerous" is required.
400invalid_idempotency_keyA raw multipart create needs an idempotency-key header. The SDK sends one for you.
409idempotency_conflictThe same idempotency key was reused with a different body.
Request failedno_qualified_target_modelNo printer in the organization can print this file. Connect a printer through HiveLink, or check the file's printer model.
Request failedplate_not_foundThe file has no plate with that number.

MCP with an API key

Headless MCP clients that cannot run an OAuth sign-in can send the same x-api-key header to https://api.printhiv3d.com/v1/mcp. Prefer OAuth when the client supports it, so each person signs in as themselves.

For agents

  • After npm install @printhive/api, read node_modules/@printhive/api/llms.txt for the calls, scopes, and the rule to ask before a print starts.
  • llms.txt summarizes the product, auth, and public endpoints.
  • Request this page with Accept: text/markdown to get Markdown instead of HTML. Pages without a Markdown version answer 404 with a list of the pages that have one.
  • The OpenAPI spec is the source for the endpoint reference. Operations with an operationId are the public contract.