Skip to main content
  1. Getting Started

Flag Consumer API Reference

Complete REST API documentation for Savvagent flag consumers. Includes evaluation, telemetry, analytics, and audit endpoints.

Base URLs

Production
https://api.savvagent.com
Beta
https://api-beta.savvagent.com

📖 Complete Documentation

For the complete, detailed API reference with all request/response examples, see the Flag Consumer API Documentation on GitHub.

Authentication

Savvagent uses two authentication methods depending on the endpoint type:

SDK API Keys

For evaluation and telemetry endpoints

Authorization: Bearer sdk_prod_...

Scoped to an application

JWT Tokens

For dashboard and analytics endpoints

Authorization: Bearer eyJhbGci...

Obtained via TOTP authentication

Core Flag Evaluation

POST /api/flags/:key/evaluate

The core feature flag evaluation endpoint. Evaluates a flag for a specific user context with advanced targeting, geolocation, scheduling, and rollout capabilities.

SDK Key Auth No JWT Required

Request Body

{
  "context": {
    "user_id": "user-123",
    "anonymous_id": "session-456",
    "organization_id": "org-uuid",
    "application_id": "app-uuid",
    "environment": "production",
    "language": "en-US",
    "attributes": {
      "plan": "premium",
      "country": "US",
      "beta_tester": true
    },
    "geolocation": {
      "country": "US",
      "city": "San Francisco",
      "continent": "NA",
      "timezone": "America/Los_Angeles",
      "latitude": 37.7749,
      "longitude": -122.4194
    }
  }
}

Response (200 OK)

{
  "key": "my-feature-flag",
  "enabled": true,
  "scope": "application",
  "configuration": {
    "theme": "dark",
    "maxItems": 100
  },
  "variation": "treatment-a",
  "timestamp": 1700000000,
  "context": {
    "user_id": "user-123"
  }
}

Evaluation Features:

  • Hierarchical flag lookup (application → enterprise)
  • Schedule-based activation/deactivation
  • Geolocation targeting (country, city, timezone, lat/long)
  • Language targeting
  • Attribute-based rules evaluation
  • Segment targeting
  • Rollout percentage with consistent hashing
  • Multi-variant support (A/B testing)
  • Redis caching (<1ms target latency)

Telemetry & Event Tracking

POST /api/telemetry/evaluations

Batch log flag evaluation events from SDKs for analytics.

JWT Auth

Request Body

{
  "events": [
    {
      "flag_key": "my-feature-flag",
      "result": true,
      "context": { "user_id": "user-123" },
      "duration_ms": 0.8,
      "trace_id": "trace-abc-123",
      "timestamp": "2025-01-18T12:34:56.789Z"
    }
  ]
}
POST /api/telemetry/errors

Batch log errors that occurred during flag evaluation or in flag-gated code.

JWT Auth

Request Body

{
  "events": [
    {
      "flag_key": "checkout-redesign",
      "flag_enabled": true,
      "error_type": "TypeError",
      "error_message": "Cannot read property 'price' of undefined",
      "stack_trace": "at processCheckout (checkout.js:45:12)...",
      "context": { "user_id": "user-789" },
      "trace_id": "trace-def-456",
      "timestamp": "2025-01-18T12:40:00.000Z"
    }
  ]
}
GET /api/telemetry/flags/:flag_id/errors

Retrieve errors associated with a specific flag.

JWT Auth

Query Parameters

  • time_range: "1h" | "24h" | "7d" (default) | "30d" | "90d"
  • limit: Integer (default: 50)

Analytics & Reporting

GET /api/analytics/flags

Get aggregated analytics for all flags in the organization.

JWT Auth

Response

[
  {
    "flag_id": "flag-uuid-1",
    "flag_key": "new-checkout",
    "flag_name": "New Checkout Flow",
    "total_unique_users": 1523,
    "enabled_users": 761,
    "disabled_users": 762,
    "actual_enabled_percentage": 49.97,
    "total_evaluations": 45230,
    "first_evaluation": "2025-01-10T08:00:00Z",
    "last_evaluation": "2025-01-18T14:30:00Z"
  }
]
GET /api/analytics/health

Check if flag rollout distributions match target percentages.

JWT Auth

Returns distribution health metrics including target vs actual percentages and skew detection.

GET /api/analytics/geo

Get geographic distribution analytics for flag evaluations.

JWT Auth

Query Parameters

  • time_range: "1h" | "24h" | "7d" (default) | "30d" | "90d"
GET /api/analytics/languages

Get language distribution analytics for flag evaluations.

JWT Auth

Query Parameters

  • time_range: "1h" | "24h" | "7d" (default) | "30d" | "90d"

Application Analytics

GET /api/organizations/:org_id/applications/:app_id/analytics

Get analytics for a specific application including daily trends and top flags.

JWT Auth

Query Parameters

  • days: Integer (default: 7, lookback period)
GET /api/organizations/:org_id/applications/analytics

Get analytics summary for all applications in the organization.

JWT Auth

Audit & History

GET /api/flags/:id/audit-log

Get audit log for a specific flag with change history and user actions.

JWT Auth

Query Parameters

  • action: Filter by action type (created, updated, deleted, etc.)
  • start_date, end_date: Date range filter
  • limit: Max results (default: 100, max: 1000)
  • offset: Pagination offset
GET /api/audit-log

Get organization-wide audit log across all flags.

JWT Auth

Required Query Parameters

  • organization_id: UUID (required)
GET /api/users/:id/activity

Get activity summary for a specific user including action counts.

JWT Auth

SDK Endpoints

Endpoints designed for SDK consumption with bulk flag retrieval and local override support.

GET /api/sdk/flags

Get all flags for the authenticated application. Returns application-scoped and enterprise-scoped flags.

SDK Key Auth

Query Parameters

  • environment: Filter by environment (e.g., "production", "development")

Response

{
  "flags": [
    {
      "key": "new-checkout",
      "enabled": true,
      "scope": "application",
      "environments": {...},
      "variations": [...],
      "configuration": {"theme": "dark"},
      "version": 5
    }
  ],
  "count": 15,
  "organization_id": "org-uuid",
  "application_id": "app-uuid"
}
GET /api/sdk/enterprise-flags

Get only enterprise-scoped flags that apply across all applications in the organization.

SDK Key Auth

Query Parameters

  • environment: Filter by environment (default: "development")

Real-Time Streaming (SSE)

Server-Sent Events endpoint for receiving real-time flag updates without polling.

GET /api/flags/stream

Subscribe to real-time flag change notifications via Server-Sent Events.

SDK Key Auth JWT Auth

Event Types

  • connected - Initial connection confirmation with context
  • flag_created - New flag created
  • flag_updated - Flag configuration changed
  • flag_deleted - Flag removed
  • heartbeat - Keep-alive ping (every 30s)

Event Payload

{
  "type": "flag_updated",
  "key": "new-checkout",
  "organization_id": "org-uuid",
  "application_id": "app-uuid",
  "environments": {"production": true},
  "version": 6
}

Tenant Isolation: SDK key auth receives only notifications for the specific application. JWT auth (admin UI) receives all notifications for the organization.

Segments (Audience Targeting)

Create and manage reusable audience segments for advanced flag targeting.

POST /api/segments

Create a new user segment with attribute-based rules.

JWT Auth

Request Body

{
  "key": "premium-users",
  "name": "Premium Users",
  "description": "Users with premium or enterprise plans",
  "rules": {
    "operator": "or",
    "rules": [
      {
        "attribute": "plan",
        "operator": "in",
        "values": ["premium", "enterprise"]
      }
    ]
  }
}
GET /api/segments List all segments
GET /api/segments/:id Get segment details
PATCH /api/segments/:id Update segment
DELETE /api/segments/:id Delete segment
JWT Auth
POST /api/segments/:id/evaluate

Evaluate if a user context matches a segment's rules.

JWT Auth

Request Body

{
  "user_id": "user-123",
  "attributes": {
    "plan": "premium",
    "country": "US"
  }
}

Response

{
  "matches": true,
  "segment_key": "premium-users"
}

AI-Powered Features

AI-powered endpoints for error correlation analysis and intelligent insights.

GET /api/ai/health

Check AI service availability and status.

JWT Auth
POST /api/ai/flags/:org_id/:flag_id/correlation

Analyze error correlation for a specific flag using AI to detect patterns.

JWT Auth

Request Body

{
  "flag_id": "flag-uuid",
  "time_window_hours": 24
}

Response

{
  "flag_id": "flag-uuid",
  "flag_key": "new-checkout",
  "analysis": {
    "correlation_score": 0.85,
    "error_types": ["TypeError", "NetworkError"],
    "recommendation": "High correlation detected...",
    "confidence": "high"
  },
  "timestamp": "2025-01-18T12:00:00Z"
}
GET /api/ai/flags/:org_id/:flag_id/insights

Get AI-generated insights and recommendations for a flag.

JWT Auth

Support Chat

AI-powered support chat for instant assistance with flag management and platform questions.

POST /api/support/conversations

Start a new support conversation with AI assistance.

JWT Auth

Request Body

{
  "initial_message": "How do I set up percentage rollouts?"
}
POST /api/support/conversations/:conversation_id/messages

Send a message in an existing conversation.

JWT Auth

Request Body

{
  "content": "Can you show me an example?"
}
GET /api/support/conversations List user's conversations
GET /api/support/conversations/:id Get conversation with messages
POST /api/support/tickets Create support ticket
GET /api/support/tickets List support tickets
JWT Auth

Error Codes & Rate Limiting

HTTP Status Codes

CodeDescription
200OK - Request successful
201Created - Resource created successfully
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid authentication
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
409Conflict - Resource conflict (e.g., duplicate key)
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong

Rate Limits

API requests are rate-limited to ensure fair usage:

  • Evaluation endpoint: 10,000 requests/minute per SDK key
  • Telemetry endpoints: 1,000 requests/minute per organization
  • Analytics endpoints: 100 requests/minute per user

Need More Details?

For complete request/response examples, evaluation logic details, and SDK integration guides, see the complete Flag Consumer API documentation.

Getting Started → SDK Documentation →

Menu

User

  • Profile
  • Organization
  • Language
  • Theme

Terms of Service

Terms of Service

Last Updated: November 25, 2025

1. Acceptance of Terms

By accessing or using the Savvagent service (the "Service"), provided by Savvagent, LLC, a Utah limited liability company, you agree to be bound by these Terms of Service ("Terms"). If you are using the Service on behalf of an organization, you represent and warrant that you have the authority to bind that organization to these Terms. If you do not agree to these Terms, you may not access or use the Service.

2. Description of Service

Savvagent provides an AI-powered feature flag management platform that enables software teams to control feature rollouts, conduct A/B testing, and correlate feature flag states with production errors. The Service includes web-based management tools, SDKs for various programming languages, APIs, and integrations with third-party observability tools through the Model Context Protocol (MCP).

3. Account Registration and Security

To access the Service, you must create an account. You agree to:

  • Provide accurate, current, and complete information during registration
  • Maintain the security of your account credentials and TOTP authenticator
  • Promptly notify us of any unauthorized access or security breach
  • Be responsible for all activities that occur under your account

4. Acceptable Use

You agree not to:

  • Use the Service in violation of any applicable laws or regulations
  • Attempt to gain unauthorized access to any part of the Service
  • Interfere with or disrupt the integrity or performance of the Service
  • Reverse engineer, decompile, or disassemble any part of the Service
  • Resell, sublicense, or transfer your rights to the Service without authorization
  • Use the Service for competitive benchmarking without prior written consent
  • Upload or transmit malicious code, viruses, or harmful data

5. Customer Data

You retain all rights to the data you submit to the Service ("Customer Data"). You grant us a limited license to process Customer Data solely to provide and improve the Service. We will not access, use, or disclose Customer Data except as necessary to provide the Service, comply with the law, or as otherwise set forth in our Privacy Policy.

Sensitive Data

You agree not to submit sensitive personal data to the Service unless you have appropriate safeguards in place. Sensitive data includes health information protected by HIPAA, payment card data subject to PCI-DSS, government identification numbers, and data protected by similar regulations.

6. Intellectual Property

The Service and all related technology, documentation, and content are the exclusive property of Savvagent, LLC and its licensors. These Terms do not grant you any rights to use our trademarks, logos, or other brand features without prior written consent.

7. Fees and Payment

Certain features of the Service require payment. Fees are non-refundable except as required by law or as expressly stated in your subscription agreement. We may change our fees upon reasonable notice. Continued use of paid features after a fee change constitutes acceptance of the new fees.

8. Termination

Either party may terminate these Terms at any time. Upon termination, your right to access the Service will cease immediately. We will retain Customer Data for 30 days following termination, after which it may be deleted. Provisions that by their nature should survive termination will survive, including intellectual property rights, disclaimers, and limitations of liability.

9. Disclaimer of Warranties

THE SERVICE IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. WE DO NOT WARRANT THAT THE SERVICE WILL BE UNINTERRUPTED, ERROR-FREE, OR COMPLETELY SECURE.

10. Limitation of Liability

TO THE MAXIMUM EXTENT PERMITTED BY LAW, SAVVAGENT SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS OR REVENUES, WHETHER INCURRED DIRECTLY OR INDIRECTLY. OUR TOTAL LIABILITY FOR ANY CLAIMS ARISING FROM OR RELATED TO THESE TERMS OR THE SERVICE SHALL NOT EXCEED THE AMOUNTS PAID BY YOU TO SAVVAGENT IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM.

11. Indemnification

You agree to indemnify, defend, and hold harmless Savvagent and its officers, directors, employees, and agents from any claims, damages, losses, liabilities, and expenses (including reasonable attorneys' fees) arising from your use of the Service, your violation of these Terms, or your violation of any rights of a third party.

12. Modifications to Terms

We may modify these Terms at any time by posting the revised Terms on our website. Material changes will be notified via email or through the Service. Your continued use of the Service after any changes constitutes acceptance of the modified Terms.

13. Governing Law and Dispute Resolution

These Terms shall be governed by and construed in accordance with the laws of the State of Utah, United States, without regard to its conflict of law provisions. You agree that any legal action or proceeding arising out of or relating to these Terms or the Service shall be brought exclusively in the state or federal courts located in Utah, and you hereby consent to the personal jurisdiction and venue of such courts.

15. Contact Information

If you have any questions about these Terms, please contact us at:

legal@savvagent.com

We use cookies

We use cookies to improve your experience on our site. Some are essential for the site to work, while others help us understand how you use it. Learn more in our Privacy Policy