Docs · API

The Hipsift API.

Find your sheets, run queries, and manage views and collections over HTTPS with an API key.

Authentication

Sign in to Hipsift, open the API Keys page and create a key. It's shown once, so copy it somewhere safe. Send it with every request:

Authorization: Bearer pfg_YOUR_API_KEY

The base URL is https://hipsift.com/api. An x-api-key header works too. Call the API from your own server or scripts: browsers on other sites can't call it.

Scopes

read: Discover data, inspect status, and run analytical queries.
write: Read access plus schedules, transforms, views, collections and other changes.
admin: Write access plus sharing views and making them public.

Area	read	write	admin
Sheets and columns	`GET /api/sheet/{id}/fields` `GET /api/sheet/{id}/dataset-info` `GET /api/sheet/{id}` `GET /api/sheet` `GET /api/field/transform`	`POST /api/sheet/{id}/header` `PUT /api/sheet/{id}` `DELETE /api/sheet/{id}` `POST /api/field/{id}/transform` `PATCH /api/field/{id}`	—
Queries	`POST /api/query/{sheetId}` `GET /api/query/{sheetId}/runs` `GET /api/query/{sheetId}/run/latest` `GET /api/query/{sheetId}/run/{queryId}`	—	—
Sources and schedules	`POST /api/source/merge/validate` `POST /api/source/merge/preview` `GET /api/source/{id}/schedule` `GET /api/source/{id}` `GET /api/source`	`POST /api/source/merge` `PUT /api/source/{id}/schedule` `PUT /api/source/{id}` `DELETE /api/source/{id}`	—
Saved views and sharing	`GET /api/view/{id}` `GET /api/view`	`POST /api/view` `PUT /api/view/{id}` `PATCH /api/view/{id}` `DELETE /api/view/{id}`	`GET /api/view/{id}/shares` `POST /api/view/{id}/shares` `DELETE /api/view/{id}/shares/{shareId}`
Collections	`GET /api/collection/{id}` `GET /api/collection`	`POST /api/collection/{id}/sheets` `POST /api/collection/{id}/views` `POST /api/collection` `PUT /api/collection/{id}` `DELETE /api/collection/{id}/sheets/{sheetId}` `DELETE /api/collection/{id}/views/{viewId}` `DELETE /api/collection/{id}`	—
Google Sheets, files and open data	`GET /api/google/spreadsheets` `GET /api/google/sheets` `GET /api/google/sheet` `GET /api/file/capabilities` `GET /api/socrata/domains` `GET /api/socrata/portals` `GET /api/socrata/catalog` `GET /api/connections/{id}` `GET /api/connections`	—	—
Import status and storage	`GET /api/ingest-queue/all` `GET /api/ingest-queue/source/{sourceId}` `GET /api/ingest-queue/{sourceId}/{sheetId}` `GET /api/ingest-queue` `GET /api/storage/usage`	—	—

Sending isPublic in the body of POST /api/view, PUT /api/view/{id} or PATCH /api/view/{id} needs an admin key.

Quickstart: total a column

Replace SHEET_ID and QUERY_ID with the ids from the steps before, and the column names with your own.

1. Find your sheets

Each sheet has a numeric id.

curl -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  https://hipsift.com/api/sheet

2. List a sheet's columns

Use each field's parquetName in queries. Totals need a number column.

curl -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  https://hipsift.com/api/sheet/SHEET_ID/fields

3. Run a query

Queries run in the background. The answer has a queryId.

curl -X POST -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selectFields":[{"fieldExpressionString":"category"}],"selectFieldFunctions":[{"functionName":"AggregateSum","args":["amount"],"alias":"total"}],"groupByFields":[{"fieldExpressionString":"category"}],"limit":100}' \
  https://hipsift.com/api/query/SHEET_ID

4. Get the result

Repeat until status is COMPLETE (the rows are in result) or ERROR.

curl -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  https://hipsift.com/api/query/SHEET_ID/run/QUERY_ID

A plain-text 404 Dataset not ingested yet means the sheet's import hasn't finished: check GET /api/ingest-queue/all and try again once it's synced. If a column holds text such as “$1,200”, add "transform": "CAST_USD" to the function.

Errors

Most errors are JSON with error, code and message. Some answer with plain text instead, so check the HTTP status first.

Status	code	Meaning
400	`invalid_request`	The request is missing or has an invalid field. An invalid query answers `errors: [{ field, message }]` instead.
401	`auth_required`	No credential, or the key is invalid or deleted.
401	`account_inactive`	The account was deleted.
401 / 403	`reauthorize_required`	The Google account needs reconnecting in the app (not a key problem).
403	`insufficient_scope`	The key's scope is too low; `requiredScope` says which is needed.
403	`paid_plan_required`	Scheduled refresh needs the Basic plan.
403	`storage_limit_reached`	The plan's storage is full.
404	`not_found`	No such resource, or it isn't yours.
404	`query_run_not_found`	Right after submitting a query, the run may not be visible yet. Retry a few times.
409	`conflict`	The request conflicts with the current state.
422	`not_socrata`	The host isn't a Socrata open-data portal.
429	`rate_limited`	Too many open-data searches; wait for `Retry-After` seconds.
502 / 503	`upstream_unavailable`	A service Hipsift depends on is unavailable. Retry.
503	`metadata_sync_failed`	A change couldn't be saved yet. Retry.
503	`entitlement_unavailable`, `storage_usage_unavailable`	Your plan or storage use couldn't be checked. Retry.
503	`service_draining`	Hipsift is restarting. Retry.
504	`upstream_timeout`	A dependency (such as Google) didn't answer in time. Retry.

Adding data

Add Google Sheets, files and open data in the Hipsift app for now. Everything you add there is available through the API.

Every operation, with its parameters and responses, is in the full API reference, where you can also try requests with your key.