# RevCent MCP Operation: `GetAPICall` This document explains how MCP/AI clients should use the `GetAPICall` operation in RevCent. `GetAPICall` retrieves the details of one specific API Call using a 20-character API Call ID. Before working deeply with API Calls, MCP/AI should read the API Calls overview: ```text https://revcent.com/documentation/markdown/mcp/operation/OverviewAPICall.md ``` The overview explains how RevCent records API Calls, how API Call sources work, how to use the `api_call` BigQuery table for lists/searches/reports, and why `GetAPICall` should be used for one known API Call only. Sources: - RevCent MCP/API schema for `GetAPICall` - RevCent MCP/API guidance for `BigQueryRunQuery` - RevCent MCP/API guidance for `GetBigQueryTables` - API Calls overview: `https://revcent.com/documentation/markdown/mcp/operation/OverviewAPICall.md` --- ## Operation Summary `GetAPICall` retrieves a single API Call record. Use this operation when: ```text The API Call ID is already known. The user wants to inspect one specific API Call. The user wants the raw request and response for one API Call. The user wants to debug one API operation. The user wants to understand the source of one API Call. The user wants related item IDs from one API Call. ``` Do not use `GetAPICall` for: ```text Lists of API Calls. Searching across API Calls. Counts. Aggregations. Metrics. Reports. Dashboards. Data mining. Bulk retrieval. API activity audits across many records. ``` For those use cases, use: ```text BigQueryRunQuery ``` against: ```sql `revcent.user.api_call` ``` --- # Read the API Calls Overview First MCP/AI should read the API Calls overview before designing or deeply analyzing API Call workflows: ```text https://revcent.com/documentation/markdown/mcp/operation/OverviewAPICall.md ``` The overview explains: ```text What API Calls are. Why RevCent records API Calls. How API Call source attribution works. How API Calls can come from API accounts, web users, system processes, webhooks, third-party shops, AI Assistants, AI Voice Agents, and AI Voice Calls. How to query the api_call BigQuery table. Why filters are important because many API Calls are recorded. When to use GetAPICall vs BigQueryRunQuery. ``` --- # Required Input | Field | Type | Required | Description | |---|---:|---:|---| | `api_call_id` | string | Yes | 20-character API Call ID. | Example request: ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX" } ``` Do not guess API Call IDs. If the user does not know the API Call ID, use `BigQueryRunQuery` to search the `api_call` table for matching API Calls. --- # What an API Call Represents An API Call is a recorded RevCent operation/request. It can represent activity from sources such as: ```text Direct API integrations. MCP clients. RevCent web app users. Internal system actions. Internal webhooks. Third-party shops. AI Assistants. AI Voice Agents. AI Voice Calls. ``` API Calls are useful because they provide operational evidence about what happened. Examples: ```text A sale was created. A refund was attempted. A note was created. Metadata was inserted. An AI Assistant triggered a Function. An AI Voice Agent attempted to process a pending sale. A third-party shop sent order data. A web app user performed an action. A system process created or updated something. ``` --- # Important Response Fields `GetAPICall` can return fields such as: | Field | Meaning | |---|---| | `id` | API Call ID. | | `created_date_unix` | Unix timestamp when the API Call was created. | | `updated_date_unix` | Unix timestamp when the API Call was last updated. | | `type` | API call type. | | `method` | API call method. | | `api_account` | API account associated with the call, if applicable. | | `ip_address` | IP address that made the API Call. | | `request` | Raw request JSON object. | | `response` | Raw response JSON object. | | `result` | API call result message. | | `is_web_app` | Whether the call was made by a user in the web app. | | `is_system` | Whether the call was made by the RevCent system. | | `is_webhook` | Whether the call was made by an internal webhook. | | `live_mode` | Whether the call was made in Live or Test mode. | | `metadata` | API Call metadata name/value pairs. | | `third_party_shop` | Originating user shop, if applicable. | | `web_user` | Originating web user, if applicable. | | related item arrays | Related RevCent item IDs created or associated with the call. | --- # Raw Request and Response A major reason to use `GetAPICall` is to inspect: ```text request response ``` These fields are useful for debugging a specific operation. Examples: ```text Why did this sale creation fail? What payload was sent? What did RevCent return? Which IDs were returned? Was the request missing a required field? Was this operation done in live mode or test mode? What error message did the API return? ``` Important: ```text Use GetAPICall for raw detail of one known API Call. Use BigQueryRunQuery to find/search/list API Calls. ``` --- # Source Attribution `GetAPICall` can help determine what created or initiated the API Call. Important source-related fields include: ```text api_account ip_address is_web_app is_system is_webhook live_mode third_party_shop web_user ``` Use these fields to answer: ```text Was this call made by an API account? Was this call made by a logged-in web app user? Was this call made by the RevCent system? Was this call made by an internal webhook? Was this call associated with a third-party shop? Was this call live or test mode? Which IP address made the call? ``` --- ## API Account Source If `api_account` is present, the call was associated with a RevCent API account. The object can include: ```text api_account.id api_account.name ``` Use this for integration debugging and audit trails. --- ## Web App Source If `is_web_app = true`, the call was made by a user in the RevCent web app. The response may include: ```text web_user.id web_user.username ``` Use this to understand which logged-in user performed an action. --- ## System Source If `is_system = true`, the call was made by the RevCent system. Use this to distinguish internal RevCent activity from external API activity or web-user activity. --- ## Webhook Source If `is_webhook = true`, the call was made by an internal webhook. Use this for webhook-driven workflow debugging. --- ## Third-Party Shop Source If `third_party_shop` is present, the call is associated with a user shop/storefront. The object can include: ```text third_party_shop.id third_party_shop.name ``` Use this to debug shop-originated activity. --- # Metadata `GetAPICall` can return metadata. Metadata entries have: | Field | Limit | Description | |---|---:|---| | `name` | 100 characters | Metadata name. | | `value` | 255 characters | Metadata value. | Example: ```json { "metadata": [ { "name": "workflow", "value": "declined_sale_recovery" } ] } ``` Metadata can help identify workflow context, external references, or automation labels associated with an API Call. --- # Related Item IDs `GetAPICall` can return arrays of related item IDs. These arrays can include: ```text sales product_sales shipping tax discounts trials subscriptions subscription_renewals invoices license_keys transactions ai_threads ai_assistants paypal_transactions offline_payments check_directs salvage_transactions pending_refunds chargebacks fraud_detections api_calls ``` These fields are important because an API Call often creates or affects other RevCent records. Examples: ```text If sales contains IDs, retrieve each sale with GetSale. If transactions contains IDs, retrieve each transaction with GetTransaction. If pending_refunds contains IDs, retrieve each refund with GetPendingRefund. If ai_threads contains IDs, retrieve each AI Thread with GetAIThread. If ai_assistants contains IDs, retrieve each AI Assistant with GetAIAssistant. If chargebacks contains IDs, retrieve each chargeback with GetChargeback. ``` This makes `GetAPICall` useful for tracing what records were created, modified, or associated with one operation. --- # GetAPICall vs BigQueryRunQuery | Goal | Correct Operation | |---|---| | Retrieve one known API Call by ID | `GetAPICall` | | Inspect raw request/response for one API Call | `GetAPICall` | | Find API Calls by date/type/source/status | `BigQueryRunQuery` | | Retrieve a list of API Calls | `BigQueryRunQuery` | | Count API Calls | `BigQueryRunQuery` | | Report success/failure rates | `BigQueryRunQuery` | | Analyze API activity by source | `BigQueryRunQuery` | | Analyze AI Assistant or AI Voice Agent activity | `BigQueryRunQuery` | | Analyze payment/refund/revenue-related API actions | `BigQueryRunQuery` | | Data mining or audits across many API Calls | `BigQueryRunQuery` | --- # Finding an API Call ID If the API Call ID is not known, do not call `GetAPICall`. Instead, use `BigQueryRunQuery` against: ```sql `revcent.user.api_call` ``` Example search for recent failed calls: ```sql SELECT created_at, id, type, method, code, api_account, is_web_app, is_system, third_party_shop FROM `revcent.user.api_call` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY) AND code != 1 ORDER BY created_at DESC LIMIT 100 ``` Then use the returned `id` with `GetAPICall`. --- # BigQuery for API Call Lists and Reports When the user asks for a list, search, metric, report, audit, dashboard, or aggregation of API Calls, use: ```text BigQueryRunQuery ``` Important: ```text RevCent records many API Calls. Apply filters when querying API Calls through BigQuery. ``` Recommended filters: ```text Date range. type. method. code. api_account. live_mode. is_web_app. is_system. is_third_party_shop. third_party_shop. user. ai_assistant. ai_voice_agent. ai_voice_call. metadata. ``` Use `GetBigQueryTables` before production SQL to confirm schemas. --- # Example: Recent API Calls, Then Get One Step 1: Use BigQuery to find the call. ```sql SELECT created_at, id, type, method, code FROM `revcent.user.api_call` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) ORDER BY created_at DESC LIMIT 50 ``` Step 2: Use `GetAPICall` on the selected ID. ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX" } ``` --- # Example: Debug One Failed Sale API Call Use `GetAPICall` after identifying the failed sale API Call ID. The response may show: ```text type method request response result sales transactions customer-related IDs api_account ip_address live_mode ``` MCP/AI can then explain: ```text What was attempted. What source made the request. Whether the request was live or test. What RevCent returned. Which related records exist. What to inspect next. ``` --- # Example: Inspect an AI Assistant API Action If a BigQuery query found an API Call associated with an AI Assistant, use `GetAPICall` to inspect the single call. Possible related fields: ```text ai_threads ai_assistants request response metadata result related item IDs ``` This helps determine what the AI Assistant actually did. --- # Example: Inspect an AI Voice Agent API Action If a BigQuery query found an API Call associated with an AI Voice Agent or AI Voice Call, use `GetAPICall` to inspect the single call. Possible uses: ```text Did the voice agent create a note? Did it insert metadata? Did it attempt a sale/payment action? Did it issue a refund? Did it trigger a Function? What request/response was returned? ``` --- # Security and Sensitive Data API Call details may include raw request and response objects. MCP/AI should treat these carefully. Be especially careful with: ```text Customer personal information. Payment-related request data. API credentials. Tokens. Secrets. Private integration data. Raw response payloads that include sensitive fields. ``` When presenting API Call details: ```text Summarize relevant operational facts. Do not expose secrets unnecessarily. Do not display raw sensitive payment data unless explicitly necessary and safe. Avoid dumping large raw request/response objects when a concise explanation is enough. ``` --- # Common Mistakes ## Mistake: Trying to Use GetAPICall Without an ID Wrong: ```text Use GetAPICall to search for recent failed API Calls. ``` Correct: ```text Use BigQueryRunQuery to find matching API Calls, then use GetAPICall for one selected ID. ``` ## Mistake: Using GetAPICall for Lists Wrong: ```text Call GetAPICall repeatedly to build a list of API Calls. ``` Correct: ```text Use BigQueryRunQuery against `revcent.user.api_call`. ``` ## Mistake: Ignoring Raw Request/Response Wrong: ```text Only check type, method, and code when debugging one failed API Call. ``` Better: ```text Use GetAPICall to inspect request, response, result, source fields, and related item IDs. ``` ## Mistake: Exposing Sensitive Data Wrong: ```text Paste the entire request/response object into a user-facing answer without checking for secrets or sensitive data. ``` Better: ```text Summarize the important operational details and avoid exposing secrets or sensitive payment information. ``` --- # MCP/AI Guidance When the user asks about API Calls: 1. Determine whether the user has a specific API Call ID. 2. If yes, use `GetAPICall`. 3. If no, use `BigQueryRunQuery` to find matching API Calls. 4. Use `GetBigQueryTables` before writing production SQL. 5. Apply filters because many API Calls are recorded. 6. Use date ranges whenever possible. 7. Use `GetAPICall` for raw request/response details after finding a specific ID. 8. Review source fields to identify origin. 9. Review related item arrays to trace affected records. 10. Avoid exposing sensitive request/response data unnecessarily. 11. Use the overview for broader API Call concepts: `https://revcent.com/documentation/markdown/mcp/operation/OverviewAPICall.md`. --- # Validation Checklist Before calling `GetAPICall`: 1. `api_call_id` is known. 2. `api_call_id` is 20 characters. 3. The user wants one specific API Call. 4. The user is not asking for a list, search, report, count, aggregation, or data mining task. 5. If the user needs to find a call first, use `BigQueryRunQuery`. 6. Prepare to inspect `request`, `response`, `result`, source fields, metadata, and related item IDs. 7. Be careful with sensitive raw request/response data. --- # Key Takeaways ```text GetAPICall retrieves one specific API Call by ID. ``` ```text Use it when the user needs raw request/response details, source attribution, metadata, result, or related item IDs for one API Call. ``` ```text Do not use GetAPICall to retrieve lists, search, report, count, aggregate, or data mine API Calls. ``` ```text Use BigQueryRunQuery against `revcent.user.api_call` for lists, searches, reports, metrics, audits, and analytics. ``` ```text RevCent records many API Calls, so BigQuery queries should use filters. ``` ```text MCP/AI should read the API Calls overview for broader context: https://revcent.com/documentation/markdown/mcp/operation/OverviewAPICall.md ``` --- Document Parent Directory * [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.