Skip to main content
OverviewGetting StartedWidget InstallationAPI ReferenceSmart ActionsScoring System
API Reference

API Reference.

Integrate Grova into your stack with the REST API.

Authentication

The Grova API supports two authentication methods:

  • JWT Bearer Token - Pass your session token in the Authorization header: Authorization: Bearer <token>
  • API Key - Use a per-project API key via the x-grova-key header. Keys are prefixed with gv_ and can be generated in your project settings.

API keys are scoped to a single project and can only access resources within that project. JWT tokens have access to all projects the authenticated user belongs to.

Endpoints

MethodPathDescription
POST/feedbackSubmit new feedback. Triggers AI triage automatically.
GET/feedbackList a paginated feedback page for one authorized project. Requires the project_id query parameter for JWT or administrative keys.
POST/feedback/:id/approveApprove a feedback item and mark it as reviewed.
POST/actions/sendSend a smart action email for a feedback item.
POST/actions/send-suggestedSend the AI-suggested action without modification.

Example: Submit Feedback

Send a POST request to create a new feedback item. The AI triage pipeline runs automatically after submission.

Request

POST /feedback HTTP/1.1
Host: grova-api-production.up.railway.app
Content-Type: application/json
x-grova-key: gv_your_project_key

{
  "message": "The checkout page crashes on Safari when I click pay.",
  "type": "bug",
  "source": "your-app",
  "email": "[email protected]",
  "metadata": {
    "browser": "Safari 17.2",
    "os": "macOS 14.3",
    "url": "/checkout"
  }
}

Response

{
  "success": true,
  "id": "fb_abc123",
  "triage_status": "queued"
}

Example: List Feedback

List requests require an authorized project scope. Pages default to 50 items and the limit is capped at 100.

GET /feedback?project_id=project_123&page=1&limit=50

{
  "items": [],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 0,
    "total_pages": 0,
    "has_more": false
  }
}

Rate Limiting

Public feedback and transcription endpoints are rate limited to 10 requests per minute per source IP. Standard rate limit headers are returned with those endpoints: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.