Skip to content
Not publicly available.This describes the Loupestack API before launch. Endpoints, limits and fields can still change.

Quickstart

From nothing to a first answer in about five minutes. You need a browser, curl, and an account at Google or GitHub whose email address is verified there.

A workspace holds your data sources, questions and dashboards. You cannot create one yourself yet: ask the Loupestack team to create one for you, or to add your email address to an existing one. You become a member the next time you log in with that address.

TODO: describe self-service sign-up once it exists.

The API uses a session cookie, not an API key (Authentication).

  1. Open https://api.dev.loupestack.com/healthz in your browser. It answers {"status":"ok"}.

  2. Open the browser’s developer console on that page and run this, with google or github:

    fetch('/api/auth/sign-in/social', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ provider: 'google', callbackURL: '/healthz' }),
    }).then((r) => r.json()).then((r) => { location.href = r.url; });
  3. Approve the login at Google or GitHub. You land back on /healthz, now logged in.

  4. In the developer tools, open the cookies of api.dev.loupestack.com and copy the value of __Secure-better-auth.session_token.

Keep it in a shell variable for the next steps. It is valid for 8 hours, and treat it like a password:

Terminal window
export LOUPESTACK_SESSION='paste-the-cookie-value-here'
Terminal window
curl https://api.dev.loupestack.com/v1/me \
--cookie "__Secure-better-auth.session_token=$LOUPESTACK_SESSION"
{
"user": { "id": "usr_3fT8kZ2bQ6vR9yWc", "name": "Owner A", "email": "owner@example.com" },
"organization": { "id": "org_7Hq2LwX9pD4mN1sK", "name": "Example Retail", "slug": "example-retail", "role": "owner" },
"organizations": [{ "id": "org_7Hq2LwX9pD4mN1sK", "name": "Example Retail", "slug": "example-retail", "role": "owner" }]
}

organization is your active workspace. If it is null, you are not a member of a workspace yet (step 1).

Terminal window
curl https://api.dev.loupestack.com/v1/sources \
--cookie "__Secure-better-auth.session_token=$LOUPESTACK_SESSION"

The answer lists the tables of your workspace’s lake and of each live source, with their columns. An empty list means nothing is connected yet: an owner or admin adds a source with POST /v1/connectors.

Requests that change something, like this one, must also send an Origin header (why). The answer streams back as server-sent events; -N makes curl print them as they arrive.

Terminal window
curl -N https://api.dev.loupestack.com/v1/ask \
--cookie "__Secure-better-auth.session_token=$LOUPESTACK_SESSION" \
--header 'Origin: https://api.dev.loupestack.com' \
--header 'Content-Type: application/json' \
--data '{ "question": "How many customers do we have?" }'
event: generating
data: {"conversationId":"3d4e5f60-7182-4930-9c4d-5e6f7a8b9cad"}
event: running
data: {"attempt":1}
event: answer
data: {"conversationId":"3d4e5f60-7182-4930-9c4d-5e6f7a8b9cad","messageId":"5f607182-93a4-4b52-9e6f-7a8b9cadbecf","summary":"You have 50 customers.","explanation":"Counted the rows of lake.customers.","executedSql":"SELECT count(*) AS customers FROM lake.customers","columns":[{"name":"customers","type":"BIGINT"}],"rows":[[50]],"truncated":false}
  • POST /v1/chat takes any message, including “create a dashboard around new customers”, and picks the flow for you.
  • Conventions covers paging, limits and retries; Errors every error code.