Embed consent-first execution in your product.

Overview

What Machinus owns—and what you keep.

Machinus is deliberately not a CRM. Its pipeline and history are created from real application/browser and response activity—not manual cards or deal values.

Search, Fetch & Memory APIs

Discover, retrieve, and remember—without confusing the jobs.

Search discovers unknown public-web sources with asearch:read key. Fetch retrieves public URLs your product already knows with an independent fetch:read key. Memoryis one account-scoped knowledge feature: save documents or facts, then retrieve the most relevant private evidence. It is a standalone API, not a browser primitive.

Search accepts any non-empty public-web question or topic up to 4,000 characters; it is not limited to jobs. Set effort to the fixed-price tiersminimal, low, medium, high, or xhigh. The legacy type values remain accepted as effort aliases; legacy auto maps to medium. Usage-based Agent modes are not exposed here. limit controls sources (1–20),connected_sources enables the configured connected data sources without exposing supplier names, and output_schemarequests structured JSON. Optionally pass source_categories:company_data (fresh company and people profiles, lead discovery, and contact research),financial_data (prices, fundamentals, earnings, filings, ownership, and screening),market_data (traffic, rankings, competitor, compliance, market, and travel signals), oraffiliate_data (product catalogs, pricing, brands, and merchant links). An optionalaccount_id attributes usage to one organization user;include_memory remains opt-in and separate.

POST /api/v1/inference
Authorization: Bearer mk_live_…   # inference:run

{
  "account_id": "acct_…",
  "idempotency_key": "summary-001",
  "prompt": "Summarize this text in three bullets."
}

POST /api/v1/search
Authorization: Bearer mk_live_…

{
  "query": "latest changes to the EU AI Act",
  "effort": "high",
  "limit": 8,
  "connected_sources": true,
  "budget": { "max_cost_dollars": 1 },
  "account_id": "…"
}

POST /api/v1/fetch
Authorization: Bearer mk_live_…

{
  "urls": ["https://example.com/pricing"],
  "mode": "text",
  "freshness": "live",
  "account_id": "…"
}

→ items[0].content_hash: sha256:…

Fetch accepts one to eight safe public HTTP(S) URLs. Choose highlights for focused evidence or text for normalized page content (and an optionalmax_characters limit). Set freshness: "live"when a check should bypass cached content. Machinus does not schedule, retry, notify, or decide what a change means: your cron, queue, or application calls Fetch again and compares the returned content_hash. A supplied account_id is optional and records the request against that account; public Fetch does not require consent.

POST /api/v1/memory/save
Authorization: Bearer mk_live_…

{
  "account_id": "…",
  "external_id": "founder-profile",
  "title": "Founder profile",
  "content": "Approved pitch deck: https://example.com/deck"
}

Use POST /api/v1/memory/search withmemory:search to retrieve the best private facts and source excerpts. Composition is explicit. Set include_memory: true on Search with anaccount_id to receive private results in a separate response section. Memory Search never sends its query to public Search; call Search separately when your product needs fresh public-web evidence. The corresponding extra scope and current account consent are always required.

Memory can also index files for an account. Sendmultipart/form-data to POST /api/v1/memory/uploadwith account_id, external_id, title, and file. Files up to 25 MB require thememory:write scope and account consent. The response is queued while Memory extracts and indexes the file; search it later with /api/v1/memory/search. Upload activity is recorded in the organization ledger.

An organization can also send an optional account_id with public Search—even without Memory—to attribute the request to one of its own users. Public Search attribution validates the account but does not require that person's consent; consent is required only for private Memory or browser work.

Remote MCP

Give any MCP-capable product governed access to Machinus.

Connect an MCP client to one remote endpoint for Search, Fetch, Memory Search, Memory Save, and the approval-gated Browser Agent. Tool discovery is capability-aware: an organization key sees only its granted scopes, while an individual connection is permanently bound to one account and never accepts an account ID.

MCP endpoint
https://machinus.xyz/api/mcp

Authorization: Bearer mk_live_…   # organization connection
Authorization: Bearer mka_…       # individual, account-bound connection

Browser Agent MCP requests create the same durable, approval-gated run as the REST API. Machinus does not expose raw browser sessions, CDP endpoints, pool credentials, or a direct bypass for customer approval.

MCP tools are not duplicate products: fetch_web is the MCP-native form of/api/v1/fetch; memory_searchis the MCP-native way to call the same Memory Search capability a REST integration reaches at /api/v1/memory/search. By contrast, tool_access.memory_search only lets the internal Browser Agent retrieve Memory during one browser task. Use the direct tool when the host needs evidence itself; use the per-run setting when the Browser Agent needs it while working.

The request_browser_agent MCP tool also accepts the same optional output_schema and browser_stateas the REST Browser Agent API. Machinus returns the readable outcome with validated output.data, ordata_valid: false when it cannot honestly satisfy the requested shape.

Architecture

One organization, many isolated external accounts.

Your product
  └─ Organization (mk_live_ API key)
       ├─ External account A
       │    ├─ secure access link + consent
       │    ├─ customer browser session, Memory, resources
       │    └─ approval-gated runs + events
       ├─ External account B
       │    └─ same hard isolation boundary
       └─ Managed execution capacity
            └─ isolated for each approved run

An external account is not a Machinus Auth user and does not consume a founder workspace. Runtime identity is generated from the account ID. Organizations cannot select, reuse, or cross another customer's browser or Memory scope.

Quickstart

Integrate in seven calls.

1. 1. Create an organization and issue a key. A signed-in operator does this in Infrastructure console. The raw key is shown exactly once.
2. 2. Provision an account. Store the returned access_url on your customer record and send it to that person.
3. 3. Sync context. Upsert typed resources that the work needs.
4. 4. Create a run. It becomes visible in the account portal after consent.
5. 5. Wait for approval. Subscribe to run.approved or poll the run/event API.
6. 6. Execute and consume output. Start the run and receive terminal state through its record or signed webhook.
7. 7. Report non-run usage. Send research, memory, proxy, storage, or workflow facts to POST /api/v1/usage with a stable idempotency key. These are raw facts, not customer-selected charges.

curl --request POST "$MACHINUS_URL/api/v1/accounts" \
  --header "Authorization: Bearer $MACHINUS_PARTNER_KEY" \
  --header "Content-Type: application/json" \
  --data '{"external_id":"student_123","display_name":"Avery Lee","profile":{"program":"Computer Science"}}'

AI integration prompt

Give your coding agent the Machinus contract.

Copy this prompt into your coding agent before asking it to build a Machinus integration. It keeps authentication, account attribution, approvals, output schemas, MCP, and billing boundaries explicit.

You are integrating Machinus into a product. Use the official documentation at https://machinus.xyz/docs and follow these rules:

1. Authenticate server-to-server with an organization mk_live_ API key. Never expose it in a browser, mobile app, prompt, or client bundle.
2. Create or update an external customer account with POST /api/v1/accounts. Keep its returned account_id in your own database.
3. Pass account_id on account-scoped calls: Browser Agent, Memory Search, Memory Save, Inference, and Computer Agent. Search and Fetch may also receive account_id when usage must be attributed to one end user.
4. Use POST /api/v1/search for public-web research, POST /api/v1/fetch for known URLs, POST /api/v1/memory/save to store facts or documents, and POST /api/v1/memory/search to retrieve private account knowledge.
5. Use POST /api/v1/browser-agent/runs for one managed browser task. It is approval-gated and returns a durable run; do not assume that creating a run means it has executed.
6. Use the output_schema option when the application needs structured data. Validate data_valid before treating the result as complete.
7. Use browser_state only for the documented account browser cache/sync behavior. Do not request raw CDP, cookies, runtime credentials, or an unrestricted browser session.
8. For recurring work, let the integrating application own scheduling, retries, queueing, and concurrency. Save a Browser Agent automation only when a reusable definition is needed.
9. For text or structured generation without a browser, use POST /api/v1/inference with the documented account and idempotency boundaries.
10. For desktop work, use the Computer Agent API: create a short-lived pairing code, pair the visible Machinus Computer Runner, then create one manifest-bounded run with POST /api/v1/computer-agent/runs. The Runner is not a raw remote desktop and has no third-party credential.
11. Computer Agent requires an explicit application/path manifest, local user approval, and network: "none". Clipboard reads, arbitrary filesystem scanning, standing permissions, and concurrent desktop control are prohibited. Scheduling, retries, and concurrency remain in the integrating application's runtime.
12. For MCP-capable hosts, use https://machinus.xyz/api/mcp. Individual mka_ credentials are permanently bound to one account; organization mk_live_ keys use scopes and account_id.
13. Treat consent, approval, idempotency keys, durable run status, local Runner permissions, and webhook signatures as mandatory reliability boundaries.
14. Attribute every request with a stable idempotency key and account_id where applicable. Read usage from GET /api/v1/usage and do not invent costs or silently retry writes.

Before writing code, state which endpoint, authentication mode, account boundary, approval state, output shape, and retry policy the integration will use. If the documentation and a requested behavior conflict, follow the documented API contract and explain the conflict.

For reusable agent behavior, the same guidance is available as a skill file at docs/skills/machinus-integration/SKILL.md.

Machinus Remote MCP endpoint:
https://machinus.xyz/api/mcp

Use a scoped mka_ credential only in your server-side or approved MCP configuration.

The skill provides workflow instructions; the MCP credential and endpoint provide the actual tools. Never place an organizationmk_live_ key in a client-side project or prompt.

Accounts & access

Provisioning, consent, and runtime access.

Every account is organization-scoped. external_id is idempotent within that organization: creating it again updates profile data and issues a fresh access link unless access_link: false is supplied.

POST /api/v1/accounts
Authorization: Bearer mk_live_...

{
  "external_id": "student_123",
  "display_name": "Avery Lee",
  "email": "[email protected]",
  "profile": { "program": "Computer Science", "graduation_year": 2027 }
}

201 Created → { object: 'partner.account', consentStatus: 'pending', access_url: 'https://…/partner-access/mka_…' }

Resources

Provide context without duplicating your CRM.

Resources are typed, account-scoped envelopes. They accept your structured data, so Machinus supports different verticals without becoming your domain system of record.

POST /api/v1/accounts/:accountId/resources

{
  "kind": "target",
  "external_id": "job_456",
  "title": "Product Designer — Example Co.",
  "data": { "url": "https://jobs.example.com/roles/456", "company": "Example Co." }
}

Browser Agent API

One managed browser agent, with only the tools you grant.

The Browser Agent API is the recommended integration surface for products that already own search, planning, CRM, or workflow orchestration. Send the task and your own context; Machinus runs the complete managed browser agent. It never exposes a raw browser session or Playwright-style actions.

POST /api/v1/browser-agent/runs
Authorization: Bearer mk_live_…

{
  "account_id": "…",
  "idempotency_key": "outreach-981",
  "prompt": "Use the supplied lead context to prepare the contact form.",
  "start_url": "https://example.com/contact",
  "context": { "lead": { "company": "Acme" } },
  "tool_access": { "search": "read", "memory_search": "off" },
  "browser_state": { "profile": "persistent", "freshness": "normal" }
}

Customer consent and exact-work approval are unchanged. When the run is approved, call its returned execute_url. The same durable status, webhooks, safe recovery, and usage ledger apply to the Browser Agent endpoint.

Browser Agent execution is organization-isolated: enabling the capability provisions one private runtime and persistent browser storage for that organization. Runtime usage for that worker belongs directly to the organization; Machinus never mixes another organization's browser runtime into it.

Browser state is not an AI tool. The runtime can operate the selected browser but cannot enumerate, export, or copy cookies, cache, local storage, or credentials. Your stable user ID maps to one Machinus account_id when you upsert the account. Re-upserting its external_id updates your metadata; it does not replace the account's browser profile.

GET /api/v1/accounts/:accountId/browser-profile   # accounts:read
POST /api/v1/accounts/:accountId/browser-profile  # accounts:write; logs out and clears state

No cookies, cached page bodies, local storage, credentials, or raw browser session are ever returned.

An active Infrastructure subscription is required before the first worker can be created. The worker has no public address and receives a tenant-derived request key rather than a platform-wide secret, so it cannot authenticate work, credentials, or browser state for another organization.

Infrastructure records reconciled product-level runtime usage. A live partial-period value is never treated as a final cost, and concurrent Browser Agent runs never expose internal runtime line items to an organization.

  "output_schema": {
    "type": "object", "additionalProperties": false,
    "required": ["total_price", "currency", "available"],
    "properties": {
      "total_price": { "type": ["number", "null"] },
      "currency": { "type": ["string", "null"] },
      "available": { "type": "boolean" }
    }
  }

An output_schema does not bypass consent or create an automatic approval rule. Your scheduler can request a future check, but each Browser Agent task executes only through the account's existing approval flow.

Computer Agent API

Bring a customer-approved computer into a bounded task.

Computer Agent is for work that genuinely needs an installed application or local files—such as a customer-authorized legacy-system export or a migration between native apps. It is not remote desktop access: Machinus uses managed execution while the paired Machinus Computer Runner exposes only the approved local action surface.

POST /api/v1/computer-agent/pairings
Authorization: Bearer mk_live_…   # computer-agent:manage

{ "account_id": "acct_…", "label": "Jane’s migration Mac" }

201 Created → { object: 'computer_agent.pairing', device_id: '…', pairing_code: '…', expires_at: '…' }

POST /api/v1/computer-agent/runs
Authorization: Bearer mk_live_…   # computer-agent:run

{
  "account_id": "acct_…",
  "device_id": "device_…",
  "idempotency_key": "legacy-export-204",
  "prompt": "Export the selected customers as a CSV.",
  "manifest": {
    "applications": ["com.example.LegacyCRM"],
    "readable_paths": ["/Users/jane/Exports"],
    "writable_paths": ["/Users/jane/Machinus Exports"],
    "network": "none",
    "allow_clipboard_write": false,
    "allow_foreground_escalation": false
  }
}

account_id is mandatory and uses the same end-user attribution model as Browser Agent, Search, Fetch, and Memory. Your own runtime owns target selection, recurrence, retries, and concurrency. Machinus owns the durable task, local approval, managed execution, boundary, and audit trail.

Mobile app

Individual Machinus on iOS and Android.

The mobile build is a Capacitor shell around the same responsive Individual Machinus web app. Browser Agent execution, queues, billing, and retries remain server-side; the phone is the place to review readiness, approve work, answer questions, and receive notifications.

pnpm mobile:sync
npx cap open ios
# or
npx cap open android

Native builds are for local testing at this stage. Push tokens are registered per signed-in user; APNs/FCM credentials are still required before production push delivery.

Saved Browser Agent automations

Turn a trusted run into a reusable, observable definition.

An automation is not a stored browser trace or a cache of an old page. It saves the reusable Browser Agent contract: prompt, optional structured-output schema, tool policy, account browser policy, defaults, and approval boundary. Each invocation creates a new durable run_id against the sameaccount_id.

POST /api/v1/browser-agent/runs/run_…/automation
Authorization: Bearer mk_live_…   # runs:read + automations:write

{
  "idempotency_key": "flight-price-mex-jfk",
  "name": "Track MEX → JFK price",
  "input_defaults": { "departure_date": "2026-10-12" }
}

Only a completed Browser Agent run can be promoted.

You can also save a definition directly with POST /api/v1/automations. Use the same fields as a Browser Agent request plus name and an organization-unique idempotency_key. Set an output_schema when you want Machinus to compare a verified observation across future runs.

POST /api/v1/automations/auto_…/runs
Authorization: Bearer mk_live_…   # browser-agent:run

{
  "idempotency_key": "flight-mex-jfk-2026-10-12-2026-09-27T18:00Z",
  "input": { "departure_date": "2026-10-12" }
}

201 Created → a new approval-gated browser_agent.run

Read GET /api/v1/automations/:automationId for its active/paused state, latest run, result, andlast_change_state. Read GET /api/v1/automations/:automationId/runs for the complete durable run history. A validated structured result is classified as first_result, unchanged, or changed. If a run has no valid structured output, its state is unavailable; Machinus never compares prose or HTML and pretends it is a tracked fact.

Machinus serializes active runs for one automation so an older check cannot finish late and overwrite the newest comparison. Your cron, queue, retries, target selection, concurrency across different automations, notifications, and cadence remain in your own runtime. Creating a future automation run does not grant blanket approval: it follows the same account consent and exact work approval flow as any other Browser Agent run.

Runs & approval

Create immutable requested work.

A run is the durable unit of work. Use an organization-unique external_id for idempotency. Browser, research, workflow, follow-up, and data-room labels all use the same account-isolated execution lane and require account-holder approval.

POST /api/v1/runs

{
  "account_id": "…",
  "external_id": "application_456",
  "capability": "browser",
  "prompt": "Prepare and submit the Product Designer application using the approved profile.",
  "target": { "name": "Product Designer — Example Co.", "url": "https://jobs.example.com/roles/456" },
  "context": { "resource_ids": ["resume_1", "job_456"] }
}

Execution

Start work only after approval.

An API key can request work, but cannot read or connect a person's runtime credentials. The execute route first proves that the run is approved, then starts managed execution with the customer's isolated browser identity. The controller receives only the bounded runtime context needed for that run.

POST /api/v1/runs/:runId/execute
Authorization: Bearer mk_live_…

202 Accepted → { object: 'partner.run', status: 'running', job_id: 'partner-run:…' }

The controller may use only requested facts, supplied context, or account-isolated Memory when the run's tool policy mounts it. It cannot invent private facts or bypass sign-in, CAPTCHA, or verification; those conditions return needsInput or needsTakeover with browser state preserved. A write-free exhaustion result may trigger bounded pool failover; writes, crashes, authentication failures, and unknown errors remain terminal for review. Terminal output may contain the structured result, form snapshot, browser write audit, and download metadata.

Usage & cost tracking

Track every infrastructure tool without guessing its cost.

Browser Agent, Inference, Search, Fetch, Memory Search, Memory Save, and their MCP counterparts record endpoint telemetry automatically. The Infrastructure dashboard groups usage by API/MCP surface and product metric, while retaining an immutable usage ledger.

Map each of your own users, customers, or workspaces to one Machinusaccount_id. Browser Agent and Memory already require it; include it on direct Search, Fetch, organization MCP Search, or organization MCP Fetch when you need per-user public-web spend. The dashboard then shows a Usage by your accounts breakdown. Your backend can retrieve the same ledger with GET /api/v1/usage and ausage:read key.

GET /api/v1/usage?account_id=acct_…&from=1767225600000
Authorization: Bearer mk_live_…   # usage:read, server-side only

POST /api/v1/usage
Authorization: Bearer mk_live_…

{ "category": "research", "metric": "search_requests", "endpoint": "your_custom_research_tool", "quantity": 25, "unit": "request", "idempotency_key": "search-batch-2026-09-26" }

Raw usage is clearly marked until it is reconciled. Hosted Memory is platform-managed and account-scoped. The dashboard places each row on the API or MCP surface that caused it; organizations and their end customers never provide or receive infrastructure keys.

Usage is tied to its API/MCP endpoint and, where known, a metric such as search_requests or browser_runtime_minutes. The API never accepts a client-selected cost.

Browser Agent usage is attributed to the account and endpoint that caused it. This gives your backend a consistent product-level usage view without exposing internal cost allocation or supplier details.

MCP uses this exact same ledger. An individual MCP credential is already bound to one account. An organization MCP host supplies account_id for Memory and Browser Agent, and when it wants public Search attributed to one of its users. MCP-created Browser Agent runs contribute to that account's runtime allocation just like REST-created runs; MCP does not create a second cost system.

Events & webhooks

Synchronize state without polling every run.

Every meaningful account and run transition appends a durable organization event. Read GET /api/v1/events, or register an HTTPS webhook. Your service supplies a secret of at least 16 characters; Machinus encrypts it with AES-256-GCM before storage.

POST /api/v1/webhooks

{
  "url": "https://your-product.example/webhooks/machinus",
  "secret": "your-long-webhook-secret",
  "events": ["run.approved", "run.submitted", "run.failed", "run.needsInput"]
}

Each receiver gets a JSON body plus x-machinus-event-id and x-machinus-signature: t=<unix-seconds>,v1=<hex-hmac>. Verify HMAC_SHA256(webhook_secret, "timestamp.raw-body") and deduplicate by event ID. Mutations attempt delivery automatically; POST /api/v1/webhooks/dispatch retries outstanding records.

Security

The enforcement model, not merely UI promises.

Use * only during early development. Production keys can be scoped to accounts:read, accounts:write, resources:read, resources:write, runs:read, runs:write, runs:execute, browser-agent:run, computer-agent:manage, computer-agent:run, automations:read, automations:write, inference:run, search:read, fetch:read, memory:search, memory:write, events:read, billing:write, webhooks:read, and webhooks:write.

Operations

Deploy and operate safely.

Endpoint reference