TextroVault API Platform Alpha V4

One core API for shared trial and dedicated inbound SMS.

Use Bearer authentication, list accessible SIM-backed phone numbers, search inbound SMS with selected-number rules, and receive signedsms.received events through filtered webhooks.

JOIN WAITLIST TALK TO US

Fast path

Already have an API key? List phone numbers, create a trial session if using a shared trial number, search SMS, then create a webhook.

Agent setup path

AI agents can initiate TextroVault onboarding by creating a bootstrap session for a human or workspace owner. TextroVault issues SMS capable trial API keys only after owner email verification.

Optional proof path

Payment method verification or dedicated prepayment can prove upgrade readiness, improve trial priority, and create a dedicated allocation request.

One core API. Two access modes:

Shared trial mode lets verified users test TextroVault API, MCP, webhook, and agent workflows through shared SIM backed trial numbers. Dedicated mode gives paid activated customers private assigned SIM backed numbers.

Shared trial numbers are shared across trial users. Do not use them for private, sensitive, financial, account recovery, or production workflows. Use dedicated numbers for private and production use.

Fast path

Start with a key you already have.

List phone numbers

curl https://api.textrovault.com/v1/phone-numbers \
  -H "Authorization: Bearer $TV_API_KEY" \
  -H "Accept: application/json"

Create shared trial session

curl https://api.textrovault.com/v1/trial-sessions \
  -H "Authorization: Bearer $TV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trial-session-001" \
  -d '{
    "phone_number_id": "pn_01JZ8N7Q5Q8G9KQ1A2B3C4D5E6",
    "sender_hint": "gifgaf",
    "ttl_seconds": 1800
  }'

Search SMS

curl https://api.textrovault.com/v1/sms/search \
  -H "Authorization: Bearer $TV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sms-search-read-001" \
  -d '{
    "phone_number_id": "pn_01JZ8N7Q5Q8G9KQ1A2B3C4D5E6",
    "trial_session_id": "ts_01JZ8N7Q5Q8G9KQ1A2B3C4D5E6",
    "filter": {
      "sender_hint": "gifgaf",
      "received_after": "2026-06-24T18:30:00Z"
    },
    "order": "desc",
    "limit": 1,
    "mark_as_read": true
  }'

Create webhook

curl https://api.textrovault.com/v1/webhooks \
  -H "Authorization: Bearer $TV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-create-001" \
  -d '{
    "url": "https://example.com/textrovault/webhook",
    "events": ["sms.received"],
    "include_body": true,
    "phone_number_id": "pn_01JZ8N7Q5Q8G9KQ1A2B3C4D5E6",
    "trial_session_id": "ts_01JZ8N7Q5Q8G9KQ1A2B3C4D5E6",
    "filter": {
      "sender_hint": "gifgaf"
    },
    "expires_in_seconds": 1800
  }'

Agent setup path

Create a verified shared-trial account without dashboard dependency.

Agent bootstrap

curl https://api.textrovault.com/v1/onboarding/agent-bootstrap \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bootstrap-001" \
  -d '{
    "owner_email": "human@example.com",
    "account_name": "Acme Agent Test",
    "principal_type": "ai_agent",
    "platform_source": "mcp",
    "agent_name": "Claude Desktop workflow",
    "intended_use": "Test inbound SMS retrieval through TextroVault API",
    "requested_capability": "shared_trial_api"
  }'

Check bootstrap status

curl https://api.textrovault.com/v1/onboarding/bootstrap/abs_01JZ... \
  -H "Authorization: Bearer $TV_BOOTSTRAP_TOKEN" \
  -H "Accept: application/json"

Issue API key

curl -X POST https://api.textrovault.com/v1/onboarding/bootstrap/abs_01JZ.../issue-api-key \
  -H "Authorization: Bearer $TV_BOOTSTRAP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: issue-key-001"

Optional proof path

Verify payment readiness or start dedicated prepayment.

Create payment verification session

curl https://api.textrovault.com/v1/onboarding/payment-verification-session \
  -H "Authorization: Bearer $TV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-verification-001" \
  -d '{
    "mode": "payment_method_verification",
    "payment_initiated_by": "ai_agent",
    "success_url": "https://example.com/textrovault/success",
    "cancel_url": "https://example.com/textrovault/cancel"
  }'

Public alpha routes

Endpoint index

POST

Create agent bootstrap session

/v1/onboarding/agent-bootstrap

Create or attach a claimable trial account for a verified owner email.

GET

Check bootstrap status

/v1/onboarding/bootstrap/{session_id}

Poll owner verification or authorization status without returning an API key.

POST

Verify owner email

/v1/onboarding/bootstrap/{session_id}/verify-email

Complete owner email verification or existing-owner authorization by code.

POST

Issue trial API key

/v1/onboarding/bootstrap/{session_id}/issue-api-key

Return the SMS-capable shared-trial API key once after owner verification.

POST

Create payment verification session

/v1/onboarding/payment-verification-session

Create an optional payment-method verification or dedicated prepayment session.

GET

List phone numbers

/v1/phone-numbers

Return accessible SIM-backed phone numbers with stable pn_ IDs and number modes.

POST

Create trial session

/v1/trial-sessions

Create a short shared-trial temporal boundary for SMS search and webhook matching.

POST

Search SMS

/v1/sms/search

Search selected-number inbound SMS with sender matching and shared-trial safeguards.

POST

Create webhook

/v1/webhooks

Create a signed sms.received webhook with dedicated or shared-trial filters.

GET

List webhooks

/v1/webhooks

List configured V4 webhooks without returning signing secrets.

DELETE

Disable webhook

/v1/webhooks/{webhook_id}

Disable a webhook while preserving delivery history.

POST

Send test event

/v1/webhooks/{webhook_id}/test

Send a signed sms.received test event to a webhook receiver.

Webhook signing

Store the webhook signing secret because it is shown only once. Verify signatures using HMAC SHA-256 over timestamp.raw_json_body.

Textrovault-Timestamp
Textrovault-Event-Id
Textrovault-Signature