Skip to content
docs
Menu
#

GraphQL Endpoint

Execute GraphQL queries for advanced data retrieval and search

POST /api/v1/graphql
On this page
#

Request

Authorization string · header · required

Bearer token for authentication

query string · body · required

The GraphQL query string

variables object · body

Variables for the GraphQL query

operationName string · body

Name of the operation to execute (for queries with multiple operations)

#

Response

data object

Query results (structure depends on the query)

errors array

Array of error objects if any errors occurred

error

message string

Error message

locations array

Location in the query where error occurred

path array

Path to the field that caused the error

extensions object

Additional error information

#

Request examples

cURL

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query SearchSessions($query: String!) { searchSessions(query: $query, limit: 10) { total results { id name rank } } }",
    "variables": {"query": "authentication bug fix"}
  }' \
  https://cloud.specstory.com/api/v1/graphql

JavaScript

const response = await fetch('https://cloud.specstory.com/api/v1/graphql', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `
      query SearchSessions($query: String!) {
        searchSessions(query: $query, limit: 10) {
          total
          results {
            id
            name
            rank
          }
        }
      }
    `,
    variables: {
      query: 'authentication bug fix'
    }
  })
});

const data = await response.json();

Python

import requests

query = """
query SearchSessions($query: String!) {
  searchSessions(query: $query, limit: 10) {
    total
    results {
      id
      name
      rank
    }
  }
}
"""

variables = {
    "query": "authentication bug fix"
}

response = requests.post(
    'https://cloud.specstory.com/api/v1/graphql',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'query': query, 'variables': variables}
)

data = response.json()
#

Response examples

200 Success

{
  "data": {
    "searchSessions": {
      "total": 3,
      "results": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "Fix authentication token validation",
          "rank": 0.95
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "name": "Debug login authentication flow",
          "rank": 0.87
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440003",
          "name": "Implement OAuth authentication",
          "rank": 0.72
        }
      ]
    }
  }
}

400 Bad Request

{
  "success": false,
  "error": "Invalid GraphQL query or variables"
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid or missing authentication token"
}