Agents, Public API, and MCP

TextMine supports two integration styles for agents and developer platforms:

Public API V3 is the primary integration path. Use it for signup, vaults, document types, uploads, tasks, records, workflows, agents, and billing.
TextMine MCP server is optional. Use it only when the client wants MCP tool discovery and tool calls instead of direct REST calls.

Need	Use
Product context	This docs site and Product map
Agent self-service signup	Agent self-service signup
Machine-readable onboarding	`https://public-api.textmine.com/.well-known/textmine-agent.json` and `https://public-api.textmine.com/v3/third-party-agents/signup/discovery`
TextMine MCP server	TextMine MCP server
MCP setup guides	TextMine MCP quickstart
Current API reference	developers.textmine.com/reference
Agent instructions for API execution	TextMine developer For Agents
ReadMe MCP endpoint	developers.textmine.com/mcp
ReadMe agent index	developers.textmine.com/llms.txt
Full developer context pack	Agent Context Pack
Integration and MCP provider catalog	Integration catalog
Self-service agents do not need MCP. They sign up through Public API V3, receive an encrypted `tm_...` service-account API key, and then call Public API V3 directly.

Which Path Should I Use?

Goal	Use	Why
Sign up a new autonomous agent	Public API V3	Signup is REST-only and does not require MCP.
Create the first vault	Public API V3	`POST /v3/vaults` with a name creates the first vault for the agent organization. The agent does not need to know a `teamId`.
Create document types and extraction questions	Public API V3	`POST /v3/document-types` configures typed processing for a vault.
Upload files and read processing status	Public API V3	`POST /v3/documents` accepts multipart uploads.
Send Workbench/task-agent instructions	Public API V3	Use `/v3/tasks` and `/v3/tasks/{taskId}/messages`.
Track free allowance and checkout state	Public API V3	Use `/v3/agent-billing/status`.
Generate an SDK or import REST endpoints into an API client	Public API OpenAPI spec	The OpenAPI spec is the canonical REST contract.
Let an MCP-native client discover TextMine tools	TextMine MCP server	Optional wrapper over TextMine capabilities for MCP clients.
Search API docs from an MCP-aware docs client	ReadMe/developer hub MCP	This is the documentation MCP endpoint, not the TextMine product MCP server.

Use the Public API base URL for the environment. For the UK multitenant deployment:

https://public-api.textmine.com

Start with machine-readable discovery:

curl https://public-api.textmine.com/.well-known/textmine-agent.json

Then create an RSA key pair in the trusted agent runtime and sign up:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out textmine-agent-private.pem
openssl rsa -pubout -in textmine-agent-private.pem -out textmine-agent-public.pem

curl -X POST https://public-api.textmine.com/v3/third-party-agents/signup/self-service \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationName": "Acme Agent Organization",
    "agentName": "Acme Contract Agent",
    "contactEmail": "billing@example.com",
    "acceptedTerms": true,
    "acceptedPrivacy": true,
    "credentialDeliveryPublicKey": "'"$(awk 'NF {sub(/\r/, ""); printf "%s\\n", $0}' textmine-agent-public.pem)"'",
    "credentialDeliveryAlgorithm": "RSA-OAEP-256"
  }'

The response includes:

credentialRef: a non-secret reference such as textmine:api-key:123
apiKeyPrefix: a display prefix that includes tm_
encryptedApiKey: the encrypted service-account API key
encryptedApiKeyAlgorithm
encryptedApiKeyEncoding
billingStatus
freeCreditsPerPeriod
setupChecklist

Decrypt encryptedApiKey in the trusted runtime, store the resulting tm_... key in a secret store, and keep the raw key out of model-visible prompts, task messages, logs, and transcripts. Use the key on future Public API calls:

Authorization: Bearer tm_...

OpenAPI Spec

Yes: provide a Public API V3 OpenAPI spec and link it from the developer hub, agent guide, and MCP docs. Agents and developers use the OpenAPI spec for REST endpoint discovery, SDK generation, typed clients, API-client imports, and exact request/response shapes. Use the published API reference at developers.textmine.com/reference. The checked-in source for the agent self-service surface is docs/openapi/textmine-public-api-v3-agent-self-service.openapi.json. The Public API OpenAPI spec should include the full self-service bootstrap path:

GET /.well-known/textmine-agent.json
GET /v3/third-party-agents/signup/discovery
POST /v3/third-party-agents/signup/self-service
GET /v3/agent-billing/status
POST /v3/vaults
POST /v3/document-types
POST /v3/documents
POST /v3/tasks
POST /v3/tasks/{taskId}/messages

MCP is different. MCP clients discover runtime tools through initialize, tools/list, and tools/call. Connector platforms may need their own OpenAPI wrapper around /mcp, but that wrapper is not the canonical Public API spec.

REST-First Bootstrap Flow

After signup:

Check allowance and setup:

curl https://public-api.textmine.com/v3/agent-billing/status \
  -H "Authorization: Bearer $TEXTMINE_API_KEY"

Create the first vault:

curl -X POST https://public-api.textmine.com/v3/vaults \
  -H "Authorization: Bearer $TEXTMINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Agent Vault"}'

Create a document type:

curl -X POST https://public-api.textmine.com/v3/document-types \
  -H "Authorization: Bearer $TEXTMINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Commercial Agreement",
    "vaultId": 123,
    "defaultTags": [
      {
        "name": "Summary",
        "question": "Summarize this document in one sentence."
      }
    ]
  }'

Upload a file:
```
curl -X POST "https://public-api.textmine.com/v3/documents?vault_id=123&document_type_id=456" \
  -H "Authorization: Bearer $TEXTMINE_API_KEY" \
  -F "file=@agreement.pdf"
```
vault_id is optional. If the agent omits it, TextMine reuses the first accessible vault or creates the default Agent Vault for that API-key organization before uploading the document.

Create and message a task:

curl -X POST https://public-api.textmine.com/v3/tasks \
  -H "Authorization: Bearer $TEXTMINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review agreement",
    "instruction": "Summarize the uploaded agreement and identify missing commercial terms.",
    "autostart": true
  }'

curl -X POST https://public-api.textmine.com/v3/tasks/789/messages \
  -H "Authorization: Bearer $TEXTMINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Also flag any unusual renewal language.","autostart":true}'

Re-check billing:

curl https://public-api.textmine.com/v3/agent-billing/status \
  -H "Authorization: Bearer $TEXTMINE_API_KEY"

Document credits are recorded when document processing completes. Agent-task credits are recorded when an agent task completes. If billing status returns checkoutRequired=true, call POST /v3/agent-billing/checkout and send the returned Stripe Checkout URL to the billing owner so they can buy a one-time credit pack.

Optional TextMine MCP Server

The hosted TextMine MCP server is a Streamable HTTP MCP endpoint backed by Public API V3. It uses the same tm_... key. Direct MCP clients can send:

Authorization: Bearer tm_...

Clients that cannot control Authorization, such as some connector platforms, can send:

GET https://public-api.textmine.com/.well-known/textmine-agent.json
GET https://public-api.textmine.com/v3/third-party-agents/signup/discovery
GET https://public-api.textmine.com/v3/third-party-agents/signup/availability
X-TextMine-Api-Key: tm_...

Streamable HTTP requires a session handshake:

Send initialize.
Keep the returned mcp-session-id response header.
Send notifications/initialized with mcp-session-id.
Call tools/list or tools/call with mcp-session-id.

A direct tools/call without mcp-session-id is rejected.

Common Confusions

https://developers.textmine.com/mcp is the developer hub documentation MCP endpoint. It helps MCP-aware clients query API docs.
The TextMine product MCP server is the hosted endpoint used to call TextMine tools.
Workbench MCP providers are third-party provider connections inside Workbench. They are not the TextMine product MCP server.
Agent self-service signup is REST-first. MCP is never required for signup.
The billing owner email collected during signup is a billing contact, not automatically a human web login.

Developer Documentation Checklist

Keep these phrases visible in page titles, descriptions, and first-screen copy:

TextMine Public API
Public API V3
OpenAPI spec
agent self-service signup
third-party agent API key
service-account API key
TextMine MCP server
MCP setup
/.well-known/textmine-agent.json

Link the agent docs, API reference, and MCP docs to each other so agents can choose the right path without guessing.

​Agents, Public API, and MCP

​Which Path Should I Use?

​Self-Service Agent Signup

​OpenAPI Spec

​REST-First Bootstrap Flow

​Optional TextMine MCP Server

​Common Confusions

​Developer Documentation Checklist