For Agents

Canonical TextMine instructions for agents using Public API V3, ReadMe MCP, the hosted TextMine MCP server, llms.txt, and agent self-service signup.

Discovery URLs

Default agent path

1. Read this page, Core Concepts, and the relevant API reference page before taking action.
2. If you do not already have a TextMine API key, use Agent self-service signup and the discovery manifest first. This is REST-first and does not require MCP.
3. Store any returned tm_... API key in a trusted runtime or secret store. Do not put it in model-visible instructions or messages.
4. Create or list Vaults before any Vault-scoped operation. For a brand-new self-service agent, POST /v3/vaults can create the first team-backed Vault workspace without a teamId.
5. Use ReadMe MCP when you need developer docs, schemas, or generated API tools. Use the TextMine-hosted MCP endpoint when you need the product MCP tool surface.
6. Prefer idempotent writes, poll asynchronous work, and show resource IDs in audit summaries.

OpenAPI and REST contract

Use the published API reference at developers.textmine.com/reference. The checked-in source for this agent self-service surface is docs/openapi/textmine-public-api-v3-agent-self-service.openapi.json.

Provide and use the canonical Public API V3 OpenAPI spec for REST endpoint discovery, SDK generation, typed clients, API-client imports, and exact request/response shapes. The spec is the source of truth for direct HTTP integrations.

MCP is a separate tool protocol. MCP-native clients discover runtime tools through initialize, tools/list, and tools/call. Connector platforms may need an OpenAPI wrapper around /mcp, but that wrapper is an adapter for the connector platform, not the canonical Public API contract.

MCP choice

Authentication

Public API V3 uses bearer API keys:

Authorization: Bearer tm_your_api_key

Agent self-service signup returns an organization-scoped service-account key. When encrypted delivery is requested, the response contains encryptedApiKey, encryptedApiKeyAlgorithm, encryptedApiKeyEncoding, credentialRef, and apiKeyPrefix; the trusted runtime decrypts and stores the secret. The model should only see credentialRef, apiKeyPrefix, and non-secret metadata.

Agent self-service provisioning

Use this only for the multitenant, non-enterprise TextMine deployment. Enterprise, private, or customer-dedicated deployments should use TextMine support-led provisioning.

1. Read GET /.well-known/textmine-agent.json or GET /v3/third-party-agents/signup/discovery.
2. Confirm GET /v3/third-party-agents/signup/availability reports signup as available.
3. Generate an RSA keypair in the trusted runtime.
4. Call POST /v3/third-party-agents/signup/self-service with organizationName, agentName, contactEmail, acceptedTerms, acceptedPrivacy, credentialDeliveryPublicKey, and credentialDeliveryAlgorithm.
5. Decrypt encryptedApiKey outside model context and call Public API V3 or the hosted MCP endpoint with Authorization: Bearer tm_...
6. Check GET /v3/agent-billing/status; when required, use checkout or portal endpoints to upgrade billing.

REST-first self-service flow

Self-service agents do not need MCP. The standard path is REST over Public API V3 using the service-account tm_... key returned by signup.

Recommended bootstrap sequence:

1. Discover availability with GET https://public-api.textmine.com/.well-known/textmine-agent.json.
2. Sign up with POST /v3/third-party-agents/signup/self-service and encrypted credential delivery.
3. Decrypt encryptedApiKey in the trusted runtime and store the tm_... key in a secret store.
4. Check setup and allowance with GET /v3/agent-billing/status.
5. Create the first workspace with POST /v3/vaults and a JSON body containing a workspace name; new agents should not need to know a teamId.
6. Create extraction types with POST /v3/document-types, passing vaultId or vaultIds plus defaultTags.
7. Upload files with POST /v3/documents as multipart form data. Pass vault_id and, for typed processing, document_type_id.
8. Create and manage long-running work with POST /v3/tasks and POST /v3/tasks/:taskId/messages.
9. Re-check GET /v3/agent-billing/status after billable work completes. Document usage is recorded when processing completes; agent-task usage is recorded when a task completes.

Product boundaries

• Vaults contain documents, folders, tags, records, workflows, and agent-visible knowledge.
• Workbench is the interactive in-app orchestration surface.
• TextMine MCP is the external agent surface.
• ReadMe MCP is the developer-hub docs/API-reference surface.
• Public API V3 is the stable integration contract for custom clients, Zapier, MCP, and self-service agents.

Common playbooks

• Upload a local document: list Vaults, choose a Vault, upload with extract=true, poll status, then inspect tags or extracted text.
• Import a provider file: list integration providers, browse folders/files, import the external file, then poll processing.
• Answer a Vault question: call the Vault ask endpoint with the Vault ID and user question.
• Generate a report: choose the report template, submit generation, then poll or fetch output.
• Create a workflow: inspect available workflow actions, create the workflow, then run or monitor it.
• Validate extracted data: fetch document tags/metadata, review source chunks or citations, then validate or update fields.