GeoGryphon API Documentation

Exchange a Google OAuth ID token for a GeoGryphon JWT session token. Use the Google Sign-In SDK to obtain the credential value.

{
  "credential": "eyJhbGciOiJSUzI1NiIs...google_id_token"
}

{
  "token": "eyJhbGciOiJIUzI1NiIs...geogryphon_jwt",
  "user": {
    "userId": "usr_a1b2c3d4",
    "email": "user@example.com",
    "name": "Jane Smith",
    "tier": "professional"
  }
}

Get the current authenticated user's profile, plan tier, and usage counters for the current billing period.

{
  "userId": "usr_a1b2c3d4",
  "email": "user@example.com",
  "name": "Jane Smith",
  "tier": "professional",
  "auditsUsed": 12,
  "briefsUsed": 5,
  "resetsAt": "2026-05-01T00:00:00.000Z",
  "paymentStatus": "ok",
  "teamOwnerId": null,
  "hasStripe": true,
  "oneTimeCredits": {
    "snapshot": 0,
    "bundle": 0,
    "brief": 0,
    "agencyPack": 0
  }
}

Permanently delete the authenticated user's account. Cancels any active Stripe subscription, wipes all audits, briefs, monitors, API keys, and team memberships. Agency owners also unlink their team members (who are downgraded to Free tier). GDPR/CCPA right-to-erasure compliant.

This action is irreversible. A typed confirmation is required in the request body to prevent accidental deletions.

{
  "confirm": "DELETE"
}

{
  "message": "Account deleted",
  "deletedAt": "2026-04-21T15:30:00.000Z"
}

Returns 400 if the confirm field is missing or not exactly "DELETE".

Generate a new API key. Must be authenticated with a JWT (not with an existing API key). Returns the key once — save it immediately; the full key is not stored and cannot be retrieved later.

{
  "apiKey": "geogryphon_a1b2c3d4e5f6...40hex",
  "prefix": "geogryphon_a1b2c3d4e5f",
  "message": "Save this key — it won't be shown again"
}

Returns 403 if the user's tier is below Professional.

Check whether the user has an active API key. Returns the prefix (first 22 chars, safe to display) and creation time, never the full key.

{
  "hasKey": true,
  "prefix": "geogryphon_a1b2c3d4e5f",
  "createdAt": "2026-04-10T12:00:00.000Z"
}

{
  "hasKey": false
}

Revoke the current API key. All subsequent requests using the revoked key will return 401 Unauthorized.

{
  "message": "API key revoked"
}

Invite a new team member by email. Emails are normalized to lowercase before storage, so case mismatches on future Google sign-in won't break the auto-link.

{
  "email": "colleague@acme.com",
  "role": "member"
}

{
  "inviteId": "inv_a1b2c3d4e5f6...",
  "email": "colleague@acme.com",
  "role": "member",
  "status": "pending"
}

List all team members (pending invites + active members). Team owners see all entries; team members see the same list read-only.

{
  "members": [
    {
      "email": "colleague@acme.com",
      "role": "member",
      "status": "active",
      "joinedAt": "2026-04-15T10:30:00.000Z"
    },
    {
      "email": "intern@acme.com",
      "role": "viewer",
      "status": "pending",
      "createdAt": "2026-04-20T14:00:00.000Z"
    }
  ]
}

Remove a team member. If the member had already signed in and was linked to your team, their tier is downgraded to Free on their next API call. URL-encode the email in the path.

{
  "message": "Team member removed"
}

Run an AI visibility audit for a domain across multiple AI engines. Checks how each engine references your brand, calculates share of voice, and compares against competitors.

{
  "domain": "acme.com",
  "keywords": ["project management", "task tracking"],
  "competitors": ["notion.so", "asana.com"]
}

{
  "auditId": "aud_x7k9m2n4",
  "userId": "usr_a1b2c3d4",
  "domain": "acme.com",
  "keywords": ["project management"],
  "createdAt": "2026-04-07T14:30:00.000Z",
  "engines": {
    "chatgpt": {
      "mentioned": true,
      "position": 2,
      "snippet": "Acme is a leading project management tool...",
      "citationUrl": "https://acme.com/features"
    },
    "perplexity": {
      "mentioned": true,
      "position": 1,
      "snippet": "For project management, Acme offers...",
      "citationUrl": "https://acme.com"
    }
  },
  "shareOfVoice": {
    "score": 0.42,
    "rank": 2,
    "totalCompetitors": 5
  },
  "comparison": [
    { "domain": "notion.so", "score": 0.58, "rank": 1 },
    { "domain": "acme.com", "score": 0.42, "rank": 2 }
  ]
}

List your audits, ordered by most recent first. Returns up to 50 audits per request.

{
  "audits": [
    {
      "auditId": "aud_x7k9m2n4",
      "domain": "acme.com",
      "keywords": ["project management"],
      "shareOfVoice": { "score": 0.42 },
      "createdAt": "2026-04-07T14:30:00.000Z"
    }
  ],
  "count": 1
}

Get the full details of a specific audit by its ID. Returns the complete audit object including all engine results and competitor comparisons.

Returns the full audit object (same structure as POST /audits response).

Generate a citation-optimized content brief. The brief includes recommended sections, entities to mention, JSON-LD structured data, and SEO guidance tailored to a specific AI engine.

{
  "topic": "Best project management tools",
  "keywords": ["project management", "team collaboration"],
  "domain": "acme.com",
  "targetEngine": "chatgpt"
}

{
  "briefId": "brf_p3q8r5s1",
  "userId": "usr_a1b2c3d4",
  "topic": "Best project management tools",
  "targetEngine": "chatgpt",
  "createdAt": "2026-04-07T15:00:00.000Z",
  "sections": [
    {
      "heading": "Introduction",
      "wordCount": 150,
      "guidance": "Lead with a clear definition. Mention your brand by name in the first paragraph..."
    },
    {
      "heading": "Feature Comparison",
      "wordCount": 400,
      "guidance": "Use a structured comparison table. Include specific metrics..."
    }
  ],
  "entities": [
    { "name": "project management", "type": "concept", "importance": "high" },
    { "name": "Acme", "type": "brand", "importance": "high" }
  ],
  "jsonLd": {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "Best project management tools",
    "author": { "@type": "Organization", "name": "Acme" }
  },
  "seoGuidance": {
    "titleTag": "Best Project Management Tools (2026) | Acme",
    "metaDescription": "Compare the best project management tools...",
    "targetWordCount": 2200,
    "readabilityLevel": "grade 8"
  }
}

List your content briefs, ordered by most recent first. Returns up to 50 briefs per request.

{
  "briefs": [
    {
      "briefId": "brf_p3q8r5s1",
      "topic": "Best project management tools",
      "targetEngine": "chatgpt",
      "createdAt": "2026-04-07T15:00:00.000Z"
    }
  ],
  "count": 1
}

Get the full details of a specific content brief by its ID.

Returns the full brief object (same structure as POST /briefs response).

Create a Stripe Checkout session to subscribe to a paid plan. Returns a URL to redirect the user to Stripe's hosted checkout page.

{
  "priceId": "price_1TJRSW7lGnd7R4baNEF1VmPV",
  "successUrl": "https://geogryphon.com/success.html",
  "cancelUrl": "https://geogryphon.com/pricing.html"
}

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "sessionId": "cs_live_..."
}

Create a Stripe Customer Portal session. The portal lets users manage their subscription, update payment methods, and view invoices.

{
  "returnUrl": "https://geogryphon.com/dashboard.html"
}

{
  "url": "https://billing.stripe.com/p/session/..."
}

Health check endpoint. Use this to verify the API is operational.

{
  "status": "ok",
  "timestamp": "2026-04-07T14:30:00.000Z"
}