GRAM API

Base URL

https://gramspec.com/gramapi

Authentication

Every request must carry an X-Api-Key header with a per-user API key. Keys are issued from your profile and begin with the prefix ormle_. A key identifies a single GramSpec user and inherits that user's permissions; only Builder and Admin accounts can use the API.

X-Api-Key: ormle_your_api_key_here

Missing or invalid keys get 401 Unauthorized. Keys belonging to Strategist/Analyst users get 403 Forbidden. Keep keys out of client-side code — treat them like a password.

Endpoints

GET /gramapi/Projects

Lists the Grammar projects owned by the authenticated user. Most callers can skip this and just pass projectName directly to Graph or BuildPrompt. Use Projects when you want to render a picker in your own app, or cache the stable projectId (which survives a project rename).

Request

curl https://gramspec.com/gramapi/Projects \
  -H "X-Api-Key: ormle_your_api_key_here"

Response

[
  {
    "projectId":   "6f1e7a5c-4b12-4d9e-9a31-6c0f88b2a4d2",
    "title":       "<project title>",
    "modifiedUtc": "2026-04-18T14:22:03Z"
  },
  {
    "projectId":   "9ab3c3e1-7e11-4d9f-a3d7-2b7f0a65e9b1",
    "title":       "<another project title>",
    "modifiedUtc": "2026-04-02T09:11:57Z"
  }
]

GET|POST /gramapi/Graph

Exports a Grammar project's GRAM knowledge graph as JSON. Identify the project by its title (projectName) — the same name you see in the Grammar project picker. Apps that want a stable machine ID (unaffected by renames) can pass projectId instead; fetch it once from /gramapi/Projects. Pass download=1 to receive the graph as a file attachment instead of an inline JSON response.

Parameters

Inline JSON (default)

curl "https://gramspec.com/gramapi/Graph?projectName=YourProjectName" \
  -H "X-Api-Key: ormle_your_api_key_here"

{
  "projectId": "6f1e7a5c-4b12-4d9e-9a31-6c0f88b2a4d2",
  "title":     "<project title>",
  "graph":     { "entities": [...], "factTypes": [...] },
  "graphJson": "{\"entities\":[...],\"factTypes\":[...]}"
}

graph is the parsed object (convenient for rendering in your own explorer); graphJson is the raw string, byte-identical to what BuildPrompt accepts on input. Prefer graphJson when you plan to round-trip the graph back to the API.

File download

curl "https://gramspec.com/gramapi/Graph?projectName=YourProjectName&download=1" \
  -H "X-Api-Key: ormle_your_api_key_here" \
  -OJ

POST /gramapi/BuildPrompt

Returns an assembled GRAM system prompt plus the component fields. Pass the prompt string as the system instruction to whichever LLM you're calling (Gemini, GPT, Claude, Grok, …) and you're done. Supply either a raw graphJson string, a projectName, or a projectId — the server loads the project and exports its graph when you identify one by name or ID.

Parameters (JSON body)

Request

curl -X POST https://gramspec.com/gramapi/BuildPrompt \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ormle_your_api_key_here" \
  -d '{
    "projectName":  "YourProjectName",
    "databaseType": "sqlserver",
    "promptMode":   "chat"
  }'

Response

{
  "prompt":       "<assembled GRAM system prompt>",
  "graphJson":    "{\"entities\":[...],\"factTypes\":[...]}",
  "graph":        { "entities": [...], "factTypes": [...] },
  "rules":        "<GRAM rules template>",
  "dialect":      "<dialect profile>",
  "databaseType": "sqlserver",
  "promptMode":   "chat"
}

prompt is the string you pass to your LLM. graph and graphJson are returned for apps that want to render the graph in their own UI. rules and dialect are returned as separate fields for apps that want direct access to each.

GET /gramapi/Rules

Returns the GRAM rules and dialect profile without any graph embedded. Useful for apps that want to fetch these once and cache them.

Request

curl "https://gramspec.com/gramapi/Rules?databaseType=snowflake" \
  -H "X-Api-Key: ormle_your_api_key_here"

Response

{
  "dialect": "<dialect profile>",
  "rules":   "<GRAM rules template>"
}

POST /gramapi/Query

Runs a natural-language prompt through GramSpec's full LLM pipeline using a saved Chat config (which owns the graph, the connection, and the user filter context). Returns the structured response the internal Chat app uses — narrative text, parsed SQL blocks, and any chart configuration.

Parameters (JSON body)

Request

curl -X POST https://gramspec.com/gramapi/Query \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ormle_your_api_key_here" \
  -d '{
    "prompt":       "Top 10 customers by revenue last quarter",
    "chatConfigId": "b1d2e3f4-5678-4abc-9def-1234567890ab",
    "provider":     "gemini",
    "promptMode":   "chat"
  }'

Response

{
  "provider": "gemini",
  "content":  "Here are the top 10 customers...",
  "raw":      "...model raw text...",
  "sqlBlocks": [
    { "title": "Top 10 Customers", "sql": "SELECT TOP 10 ..." }
  ],
  "chart":    { "type": "bar", "x": "CustomerName", "y": "Revenue" }
}

Supported databases

databaseType accepts the dialects the GramSpec prompt engine ships rules for:

• sqlserver — Microsoft SQL Server (T-SQL)
• snowflake — Snowflake
• postgresql — PostgreSQL
• mysql — MySQL
• mariadb — MariaDB
• databricks — Databricks SQL

Anything else falls back to a generic SQL profile. SharePoint graphs are not supported by this API at this time — requests with databaseType: "sharepoint" are rejected with 400.

End-to-end examples

Python

import requests

API_KEY  = "ormle_your_api_key_here"
BASE_URL = "https://gramspec.com/gramapi"
HEADERS  = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

# Optional: list your projects. You can skip this and pass the
# project title you already know directly to BuildPrompt.
projects = requests.get(f"{BASE_URL}/Projects", headers=HEADERS).json()
project_name = projects[0]["title"]

# Assemble the full system prompt
resp = requests.post(
    f"{BASE_URL}/BuildPrompt",
    headers=HEADERS,
    json={
        "projectName":  project_name,
        "databaseType": "sqlserver",
        "promptMode":   "chat",
    },
)
system_prompt = resp.json()["prompt"]

# Hand system_prompt to your LLM of choice
# (Gemini, GPT, Claude, Grok, ...) as the system instruction.

C# / .NET

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "ormle_your_api_key_here");

var payload = JsonConvert.SerializeObject(new
{
    projectName  = "YourProjectName",
    databaseType = "sqlserver",
    promptMode   = "chat"
});

var response = await client.PostAsync(
    "https://gramspec.com/gramapi/BuildPrompt",
    new StringContent(payload, Encoding.UTF8, "application/json"));

dynamic result = JsonConvert.DeserializeObject(
    await response.Content.ReadAsStringAsync());

string systemPrompt = result.prompt;

Error responses

All error responses are JSON of the form { "error": "message" }.

Getting an API key

1. Make sure your GramSpec account is on the Builder tier. See Pricing to upgrade.
2. Open your profile and scroll to the API keys section.
3. Generate a new key, copy it immediately (the full value is shown only once), and store it in your secret manager.
4. Send it as X-Api-Key on every request.

If you suspect a key has been leaked, revoke it from the same profile section and issue a new one — revoked keys stop working immediately.

See also

• GRAM Specification v1.0 — the formal standard the API's rules are built on.
• Features — what the GramSpec platform does around this API.
• About — why GRAM exists.