API Reference

Troubleshooting

Runs the ResolveGrid AI troubleshooting agent against a symptom and asset context. The call is stateless; pass a conversation_id to continue a prior exchange. Responses are grounded only in the tenant's published knowledge and cite their sources.

POST /v1/troubleshoot

{
  "asset_id": "ast_7f3a",
  "symptom": "Chiller trips on high discharge pressure within 10 minutes of start",
  "observations": [ "Condenser water inlet 95F", "Fault code 221" ],
  "external_ref": "WOT0012345"
}

{
  "id": "ts_9c1e",
  "causes": [
    { "rank": 1, "cause": "Condenser water flow restriction", "confidence": 0.72 },
    { "rank": 2, "cause": "Failed discharge pressure transducer", "confidence": 0.19 }
  ],
  "procedure": { "title": "Verify condenser water flow", "steps": [ "..." ] },
  "sources": [ { "knowledge_id": "kn_44", "title": "19XR Service Manual, sec. 7.3" } ],
  "escalate": { "recommended": false }
}

• POST /v1/troubleshoot/{id}/feedback Record whether the recommendation resolved the issue. Feeds the knowledge loop.

Troubleshooting calls count toward the plan's monthly allowance; see rate limits.

Knowledge

The knowledge store holds the manuals, procedures, articles, and past resolutions that ground every answer. Content uploaded but not published stays invisible to the AI.

• GET /v1/knowledge/search?q=&asset_id= Semantic search; returns passages with source and score
• GET /v1/knowledge/{id} A document or article with its sections and citation metadata
• POST /v1/knowledge Upload a document or article and attach it to an asset model
• POST /v1/knowledge/sync Register an external source such as a ServiceNow knowledge base (later release)

Assets

Assets can be native ResolveGrid records or mirrored from your CMDB. Asset context is what the AI and the MCP tools read first.

• GET /v1/assets/{id} Model, serial, site, install base, and attached knowledge
• GET /v1/assets/{id}/history Sessions, troubleshooting runs, and resolutions for the asset, newest first
• POST /v1/assets/identify Resolve a photo, nameplate text, or barcode to an asset (later release)

Tenant administration

Requires the admin scope.

• GET and POST /v1/users Provision users; supports SSO-linked accounts
• GET and POST /v1/skill-groups Expert groups that sessions can be routed to
• GET and POST /v1/api-keys Create, list, and revoke scoped keys
• GET and POST /v1/webhooks Register endpoints and choose events

Webhooks

ResolveGrid sends a signed POST to your endpoint when an event occurs. Every payload carries the external_ref you supplied. Deliveries are retried with exponential backoff for 24 hours.

• session.created, session.started, session.ended
• session.summary_ready
• troubleshoot.completed
• knowledge.article_proposed

POST https://your-system.example.com/resolvegrid
ResolveGrid-Signature: t=1761508800,v1=5f1a...
Content-Type: application/json

{
  "id": "evt_2b8",
  "type": "session.summary_ready",
  "created_at": "2026-10-26T20:02:11Z",
  "data": { "session_id": "ses_01HZX", "external_ref": "WOT0012345" }
}

Verify the signature by computing an HMAC-SHA256 of t and the raw body with your webhook secret and comparing it to v1.

Errors

Errors use standard HTTP status codes and a JSON body with a stable code.

• 400 invalid_request A required field is missing or malformed
• 401 unauthorized Missing or expired token
• 403 insufficient_scope Token lacks the scope this endpoint requires
• 404 not_found No object with that ID in this tenant
• 409 idempotency_conflict Same key reused with a different payload
• 429 rate_limited See Retry-After
• 500 internal_error Retry with backoff; include the request_id when contacting support

{
  "error": { "code": "insufficient_scope", "message": "sessions:write required", "request_id": "req_7d2" }
}

Rate limits and allowances

Per-tenant and per-token limits apply to every endpoint and are reported in RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Sessions, summaries, knowledge search, asset context, and webhooks are unlimited within fair use. POST /v1/troubleshoot is metered against the plan's monthly allowance; usage packs are available for agents that need more.

MCP server

The ResolveGrid MCP server is a remote server using Streamable HTTP and OAuth 2.1. Each tenant has its own endpoint, and discovery metadata is published at the standard well-known path.

https://mcp.resolvegrid.ai/{tenant}

Tools map one-to-one onto the endpoints above and require the same scopes. Every tool returns structured JSON plus a short summary an agent or a person can read.

• get_asset_context Asset record, install base, open work orders, recent sessions (assets:read, sessions:read)
• troubleshoot Ranked causes, recommended procedure, sources (troubleshoot)
• search_knowledge Semantic search over tenant knowledge (knowledge:read)
• create_assist_session Browser-mode link and app deep link, tied to an external reference (sessions:write)
• get_session_status Live state of a session (sessions:read)
• get_session_summary AI summary of a completed session (sessions:read)
• record_resolution Writes the outcome to the system of record (sessions:write)

Resources: resolvegrid://sessions/{id}, resolvegrid://assets/{id}/history, resolvegrid://knowledge/{id}. Prompts: diagnose_work_order, summarize_for_handoff.

Connect a client

{
  "mcpServers": {
    "resolvegrid": {
      "url": "https://mcp.resolvegrid.ai/acme",
      "transport": "streamable-http"
    }
  }
}

In ServiceNow, register the server in AI Agent Studio and add it to an agent as an MCP server tool. In Claude, add it as a connector and approve the OAuth prompt. Any other MCP client works the same way.

Versioning

The API is versioned in the path. Fields are only added within a version, never removed or renamed. Breaking changes ship as a new version with at least twelve months of overlap.