The Hipsift API.

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 imports, schedules, transforms, views, collections and other changes.
• admin: Write access plus sharing views and making them public.

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.

Importing data

Imports need a write key, count toward your plan's storage, and run in the background. To upload a file instead of linking to it, use POST /api/file/presign first (see the reference). Google Sheets and open data can be refreshed later with POST /api/source/SOURCE_ID/resync-now; to update a file, add the new one and delete the old source.

Add a Google Sheet

Use a spreadsheetId from GET /api/google/spreadsheets (spreadsheets you've picked in Hipsift). Add connectionId (the id from GET /api/connections) if you have more than one Google account, or no Google Sheets in Hipsift yet.

curl -X POST -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spreadsheetId":"SPREADSHEET_ID"}' \
  https://hipsift.com/api/sheet-sync

Add a file from a URL

A public HTTPS link to a Parquet or CSV file. requestId is a new random UUID (for example from uuidgen); sending the same one again is safe.

curl -X POST -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"csv","fileName":"orders.csv","sourceKind":"url","url":"https://example.com/orders.csv","requestId":"REQUEST_UUID"}' \
  https://hipsift.com/api/file/ingest

Add an open-data dataset

The dataset's page on a Socrata portal.

curl -X POST -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://data.example.gov/d/abcd-1234"}' \
  https://hipsift.com/api/socrata/ingest

Wait for the import

Use the sourceId from the import's answer. Repeat until the list isn't empty and every sheet's status is SYNCED (or FAILED, with an error).

curl -H "Authorization: Bearer pfg_YOUR_API_KEY" \
  https://hipsift.com/api/ingest-queue/source/SOURCE_ID