API Endpoints

API Endpoints

1. Agent Discovery Endpoint

Purpose: Get agent metadata, capabilities, and skills

URL: https://agent.stactize.com/.well-known/agent-card.json

Method: GET

Authentication: None (public endpoint)

Response:

{
  "name": "SaaS Research Agent",
  "version": "1.1.0",
  "description": "AI-powered agent for comprehensive SaaS company research...",
  "provider": {
    "organization": "Stactize",
    "url": "https://stactize.com"
  },
  "capabilities": {
    "streaming": true,
    "extensions": [
      {
        "uri": "https://cloud.google.com/marketplace/docs/partners/ai-agents/setup-dcr",
        "description": "Dynamic Client Registration for Gemini Enterprise",
        "params": {
          "target_url": "https://agent.stactize.com/dcr"
        }
      }
    ]
  },
  "security_schemes": {
    "google_oauth": {
      "type": "oauth2",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
          "tokenUrl": "https://oauth2.googleapis.com/token",
          "scopes": {
            "profile": "User profile information",
            "email": "User email address"
          }
        }
      }
    },
    "api_key": {
      "type": "apiKey",
      "name": "x-api-key",
      "in": "header"
    }
  },
  "security": [
    {"google_oauth": ["profile", "email"]},
    {"api_key": []}
  ],
  "skills": [
    {
      "id": "saas_company_research",
      "name": "SaaS Company Research",
      "description": "Comprehensive research and analysis...",
      "tags": ["saas", "research", "competitive-intelligence"]
    },
    {
      "id": "competitive_analysis",
      "name": "Competitive Analysis",
      "description": "Detailed competitive landscape analysis...",
      "tags": ["competitive-analysis", "market-research"]
    },
    {
      "id": "pricing_analysis",
      "name": "SaaS Pricing Analysis",
      "description": "In-depth analysis of SaaS pricing models...",
      "tags": ["pricing", "saas", "subscription-models"]
    }
  ]
}

Use Cases:
– Discover agent capabilities before integration
– Validate agent version in CI/CD
– Display available skills in UI

2. Message Send Endpoint (Non-Streaming)

Purpose: Send a research request and receive complete response

URL: https://agent.stactize.com/

Method: POST

Authentication: API Key required

Request Format (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "messageId": "msg-unique-id-12345",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Research Salesforce and provide competitive analysis"
        }
      ]
    }
  },
  "id": 1
}

Headers:

x-api-key: YOUR_API_KEY
x-user-id: user-12345
Content-Type: application/json

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task-abc-123",
    "contextId": "ctx-xyz-789",
    "status": {
      "state": "completed",
      "message": {
        "messageId": "msg-response-456",
        "role": "agent",
        "parts": [
          {
            "type": "text",
            "text": "Research completed successfully"
          }
        ]
      }
    },
    "artifacts": [
      {
        "name": "saas_research_report",
        "parts": [
          {
            "type": "text",
            "text": "# Salesforce Research Report\n\n## Company Overview\n..."
          }
        ]
      }
    ]
  }
}

Timeout: 300 seconds (5 minutes)

3. Message Stream Endpoint (Streaming)

Purpose: Send request and stream response in real-time

URL: https://agent.stactize.com/

Method: POST

Authentication: API Key required

Request Format:

{
  "jsonrpc": "2.0",
  "method": "message/stream",
  "params": {
    "message": {
      "messageId": "msg-stream-12345",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Analyze Slack pricing and compare with competitors"
        }
      ]
    }
  },
  "id": 2
}

Response: Server-Sent Events (SSE) stream with task updates

Benefits:
– Real-time progress updates
– Lower perceived latency
– Better UX for long-running queries