Agent self-service signup

Use agent self-service signup when an autonomous third-party agent needs its own TextMine organization, service-account API key, and billing account. Signup and setup are REST-first through Public API V3; MCP is optional after the API key exists.

This flow is for the multitenant, non-enterprise TextMine deployment only. Enterprise, private, and customer-dedicated deployments should use TextMine support-led provisioning.

What signup creates

A successful signup provisions:

• A TextMine corporate organization for the agent workspace.
• A hidden service-account user for the external agent.
• An organization-scoped tm_... API key for Public API V3 and optional TextMine-hosted MCP calls.
• A billing account with free credits and upgrade/portal links.
• Agent setup checklist metadata returned to the caller.

The billing contact email is not automatically a human login. If a human needs web access to the same organization, request support-led user access for that organization.

Public API base URL

For the UK multitenant deployment, use:

https://public-api.textmine.com

Do not use https://app.textmine.com for signup or Public API V3 calls. The app host is the product web/MCP host; the Public API host is the REST host.

Discovery endpoints

The discovery response includes required fields, required acceptances, terms/privacy URLs and versions, free-credit pricing, billing endpoints, authentication guidance, MCP metadata, and setup checklist steps.

Secure credential delivery

Generate an RSA keypair in the trusted agent runtime, not in model-visible context. Send the public key in the signup request:

{
  "organizationName": "Acme Agent Workspace",
  "agentName": "Acme Contract Agent",
  "contactEmail": "[email protected]",
  "acceptedTerms": true,
  "acceptedPrivacy": true,
  "credentialDeliveryPublicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "credentialDeliveryAlgorithm": "RSA-OAEP-256"
}

With encrypted delivery, the response includes:

• organizationId
• serviceAccountUserId
• apiKeyId
• apiKeyPrefix
• credentialRef
• encryptedApiKey
• encryptedApiKeyAlgorithm
• encryptedApiKeyEncoding
• billingStatus
• freeCreditsPerPeriod
• gettingStarted
• setupChecklist

The trusted runtime decrypts encryptedApiKey, stores the raw tm_... API key in a secret store, and injects it into future API or MCP requests. The model should only see credentialRef, apiKeyPrefix, resource IDs, and non-secret setup metadata.

After signup

Use the API key with Public API V3:

Authorization: Bearer tm_your_api_key

Use it with the TextMine-hosted MCP endpoint when your client supports remote MCP headers:

{
  "url": "https://app.textmine.com/mcp",
  "headers": {
    "Authorization": "Bearer tm_your_api_key"
  }
}

Then follow the setup checklist returned by signup. Typical first steps are listing Vaults, creating/importing documents, polling document status, fetching tags/metadata/plain text/source chunks, creating records or workflows, and checking billing state before heavier work.

REST-first setup 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.

OpenAPI spec

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.

Use the canonical Public API V3 OpenAPI spec in the developer hub for SDK generation, typed clients, API-client imports, and exact request/response shapes. The spec should include the full self-service path: discovery, signup, billing status, vault creation, document type creation, document upload, task creation/messages, and usage tracking.

MCP tool schemas are discovered at runtime by MCP clients. They do not replace the REST OpenAPI spec.

Billing and upgrades

Agent billing endpoints:

• GET /v3/agent-billing/status
• POST /v3/agent-billing/checkout
• POST /v3/agent-billing/portal

If the free allowance is exhausted and checkout is required, API-key work can return 402 Payment Required. Fetch billing status, create a checkout session, or open the billing portal as directed by the response.

Human access

The service-account key belongs to the agent. Do not share it with a human operator. Human users should be added to the organization separately and should use their own web session or their own permitted API key.

Dedicated deployments

Do not use this self-service flow for enterprise, private, or customer-dedicated environments. Use TextMine support-led provisioning so the organization, access model, billing posture, and environment-specific hosts are configured correctly.