Demo guide

Testing the API with a demo account

Use this walkthrough to try the common API flows with the demo key created by the app.

Set up your terminal

These examples use environment variables so the API key is not repeated in every command.

Example

export API_BASE_URL=https://shipdeploy.work/api/v1
export DEMO_API_KEY=replace-with-your-demo-api-key

Check service health

Health does not require an API key. It confirms the app is reachable before you test account API routes.

Example

curl https://shipdeploy.work/health.json

Create one record

This stores a flexible JSON entity in your demo account.

Example

curl -X POST "$API_BASE_URL/entities.json" \
  -H 'content-type: application/json' \
  -H 'x-api-key: $DEMO_API_KEY' \
  -d '{"id":"person-ada","type":"person","data":{"name":"Ada","active":true,"department":"research"}}'

Find a record by id

Use this when you already know the entity id.

Example

curl -X POST "$API_BASE_URL/queries/find-entity-by-id.json" \
  -H 'content-type: application/json' \
  -H 'x-api-key: $DEMO_API_KEY' \
  -d '{"id":"person-ada"}'

Create multiple records in one transaction

By default, batch creation is all-or-nothing. If one insert fails, the full batch rolls back.

Example

curl -X POST "$API_BASE_URL/entities/batch.json" \
  -H 'content-type: application/json' \
  -H 'x-api-key: $DEMO_API_KEY' \
  -d '{"transaction":true,"entities":[{"id":"person-grace","type":"person","data":{"name":"Grace"}},{"id":"person-katherine","type":"person","data":{"name":"Katherine"}}]}'

Create multiple records without a transaction

Set transaction to false when you want independent per-record results. One failure does not prevent the other inserts.

Example

curl -X POST "$API_BASE_URL/entities/batch.json" \
  -H 'content-type: application/json' \
  -H 'x-api-key: $DEMO_API_KEY' \
  -d '{"transaction":false,"entities":[{"id":"person-grace","type":"person","data":{"name":"Grace Hopper"}},{"id":"person-dorothy","type":"person","data":{"name":"Dorothy"}}]}'

List records by type

This is the quickest way to inspect records of the same kind.

Example

curl -X POST "$API_BASE_URL/queries/find-entities-by-type.json" \
  -H 'content-type: application/json' \
  -H 'x-api-key: $DEMO_API_KEY' \
  -d '{"type":"person","page":1,"page-size":20,"sort-by":"updated-at","sort-direction":"desc"}'

Inspect schema from stored data

After writing records, sample the account data to see common fields and exceptions.

Example

curl -X POST "$API_BASE_URL/schema/sample-by-type.json" \
  -H 'content-type: application/json' \
  -H 'x-api-key: $DEMO_API_KEY' \
  -d '{"type":"person","sample-size":20}'

Review entity history

Every create, update, upsert, and delete records change metadata. Evict permanently removes the entity and its full history.

Example

curl -X POST "$API_BASE_URL/entities/history.json" \
  -H 'content-type: application/json' \
  -H 'x-api-key: $DEMO_API_KEY' \
  -d '{"id":"person-ada","page":1,"page-size":20}'

What happens when it expires

Expired demo API keys stop authenticating automatically. The app can then remove the expired demo account, API keys, queries, records, and history rows together.