OpenAPI / REST Integrations

ChatGPT Actions

Import the OpenAPI spec as a Custom GPT Action.

Recommended: For the best ChatGPT experience, use the ChatGPT App Integration instead. That path gives you OAuth account linking, native tool discovery, and the Brand Snapshot widget inside ChatGPT. This page documents the legacy OpenAPI Actions flow for Custom GPTs that need API-key-based access.

Connect SocialCRM to ChatGPT via Custom GPT Actions. Your GPT gets access to the SocialCRM REST/OpenAPI surface through the OpenAPI spec.

Prerequisites

  • ChatGPT Plus or Pro account (required for Custom GPTs)
  • SocialCRM account with API key (get one from Settings > API Keys)

Quick Start

1. Get your API key

Generate an API key from Settings > API Keys.

2. Create or edit a Custom GPT

Go to ChatGPT > Explore GPTs > Create (or edit an existing GPT). Navigate to Configure > Actions > Create new action.

3. Import the OpenAPI spec

Select "Import from URL" and enter:

https://socialcrm.com/api/mcp-app/openapi.json

The spec is publicly accessible — no auth required to fetch it. ChatGPT will import all 21 tools automatically.

4. Configure authentication

In the Action settings:

  • Authentication type: API Key
  • Auth Type: Bearer
  • API Key: sk_live_YOUR_KEY_HERE

5. Test and save

Click Test to verify the connection. Ask the GPT to "list my brand profiles" to confirm tools are working. Save the action.

Alternative: Manual Schema

If you prefer to paste the schema directly instead of importing from URL:

{
  "openapi": "3.0.0",
  "info": {
    "title": "SocialCRM API",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://socialcrm.com/api" }
  ],
  "paths": {
    "/mcp-app": {
      "post": {
        "summary": "Call a SocialCRM tool",
        "operationId": "callTool",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": { "type": "string", "example": "2.0" },
                  "id": { "type": "string" },
                  "method": { "type": "string", "example": "tools/call" },
                  "params": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string" },
                      "arguments": { "type": "object" }
                    },
                    "required": ["name"]
                  }
                },
                "required": ["jsonrpc", "id", "method", "params"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Tool result" } },
        "security": [{ "BearerAuth": [] }]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": { "type": "http", "scheme": "bearer" }
    }
  }
}

What You Can Ask

Once your GPT has the SocialCRM action, you can ask:

  • "List my brand profiles"
  • "What is my visibility score on ChatGPT and Claude?"
  • "Get recent mentions of Acme across the core benchmarked engines"
  • "Run the AI Citation Builder workflow"
  • "Check my credit balance"

REST Endpoints

Each tool is also available as a standalone REST endpoint (useful for testing outside ChatGPT):

POST https://socialcrm.com/api/mcp-app/rest/{tool_name}
Authorization: Bearer sk_live_...
Content-Type: application/json

{ ...tool arguments... }

Response is the tool's data object directly (no JSON-RPC wrapping). Tools with no required parameters accept an empty body {}.

Available Tools

Brand & Analytics (10): list_brand_profiles, get_brand_profile, get_competitors, get_repository_items, search_repository_items, get_platform_metrics, get_brand_mentions, get_monitoring_results, get_metric_trend, get_agent_run_summary

Insights & Alerts (5): get_ai_visibility_score, get_dashboard_overview, list_simulations, get_competitor_rankings, list_notifications

Workflows (6): list_workflows, get_credits, run_workflow, get_run_status, list_workflow_runs, cancel_workflow_run

Notes

  • companyId is auto-injected from your API key — the GPT does not need to know or pass it.
  • brandId parameters accept either a UUID or a brand name (resolved automatically).
  • Rate limits: 60 req/min general, 10 req/min for mutating operations (run_workflow, cancel_workflow_run).
  • Error responses return { "error": { "code": "...", "message": "..." } } with appropriate HTTP status codes (400, 401, 429, 500).