API Documentation

Note: Every API request must include the correct profile header to specify your tenant ID. Your tenant ID can be found under Settings in your app along with your API key. Users are authenticated via JWT tokens.

1. Authentication & Schema Selection

Authentication Flow

Login

POST https://api.gather-grid.com/auth/v1/token?grant_type=password
Headers:
Content-Type: application/json
apikey: YOUR_API_KEY
For write operations on this endpoint, include: 
Content-Profile: YOUR_TENANT_ID
Request Body:
{
  "email": "admin@example.com",
  "password": "your_password"
}
Response:
{
  "access_token": "USER_JWT_TOKEN",
  "refresh_token": "USER_REFRESH_TOKEN",
  "expires_in": 3600,
  "token_type": "bearer"
}

The returned JWT token will include your tenant's information.

Using the JWT Token & Specifying Your Tenant Schema

For GET (read) requests: Include the header:

Accept-Profile: YOUR_TENANT_ID

For POST/PATCH/DELETE (write) requests: Include the header:

Content-Profile: YOUR_TENANT_ID

If you also want the response (using Prefer: return=representation), include:

Accept-Profile: YOUR_TENANT_ID

Common headers for all subsequent requests:

Authorization: Bearer USER_JWT_TOKEN
apikey: YOUR_API_KEY
Content-Type: application/json

2. Endpoints

A. Reading Data (GET Requests)

When making GET requests, include the header:

Accept-Profile: YOUR_TENANT_ID

Retrieve List of Things

GET https://api.gather-grid.com/rest/v1/things

Description: Retrieves a list of "things" — the primary entities in your system.

Query Parameters:
  • limit — Number of items to return (e.g., ?limit=10)
  • offset — Number of items to skip (e.g., ?offset=0)
Example Request:
GET https://api.gather-grid.com/rest/v1/things?limit=10
Headers:
apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Accept-Profile: YOUR_TENANT_ID
Content-Type: application/json

Retrieve Entries

GET https://api.gather-grid.com/rest/v1/entries

Description: Retrieves a list of entries associated with your "things". You can filter by specific fields (e.g., thing_id).

Query Parameters:
  • Filter (e.g., ?thing_id=eq.123)
  • Pagination (e.g., ?limit=20&offset=0)
Example Request:
GET https://api.gather-grid.com/rest/v1/entries?thing_id=eq.123&limit=20

Headers: Same as above.

Retrieve Fields

GET https://api.gather-grid.com/rest/v1/fields

Description: Retrieves field definitions for your "things", including flags such as mandatory and required-for-initialization.

Example Request:
GET https://api.gather-grid.com/rest/v1/fields?thing_id=eq.123

Headers: Same as above.

Retrieve Field Entries

GET https://api.gather-grid.com/rest/v1/field_entries

Description: Retrieves individual field values linked to an entry.

Example Request:
GET https://api.gather-grid.com/rest/v1/field_entries?entry_id=eq.456

Headers: Same as above.

B. Creating Data (POST Requests)

For POST requests, include the header:

Content-Profile: YOUR_TENANT_ID

(Prefer: return=representation if you want the response to include the created record.)

Create a New Entry

POST https://api.gather-grid.com/rest/v1/entries

Description: Create a new entry in your system. The database will automatically assign the entry ID.

Headers:
apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Content-Type: application/json
Content-Profile: YOUR_TENANT_ID

If you want to receive the created record in the response, also include:

Accept-Profile: YOUR_TENANT_ID
Prefer: return=representation
Request Body Example:
{
  "thing_id": 123
}
Response Example:
[
  {
    "id": 321,
    "thing_id": 123,
    "classification_item_id": null,
    "classification_item_name": null,
    "validity_start_date": null,
    "validity_end_date": null,
    "created_by": null,
    "created_at": "20250305T034910.74340000",
    "updated_at": "20250305T034910.74340000"
  }
]

Next Steps: Use the returned entry ID (e.g., 321) to create associated records in the field_entries table.

Create Field Entries

POST https://api.gather-grid.com/rest/v1/field_entries

Description: For each required field in the new entry, create a record in the field_entries table. This links the new entry (using the entry ID) to a specific field and assigns a value.

Headers:
apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Content-Type: application/json
Content-Profile: YOUR_TENANT_ID
Request Body Example:
{
  "entry_id": 321,
  "field_id": 4,
  "entered_value": "Value for Field 4"
}

C. Updating Data (PATCH Requests)

For PATCH (or other write) requests, include the header:

Content-Profile: YOUR_TENANT_ID

Optionally include Accept-Profile: YOUR_TENANT_ID if returning updated records is desired.

Update an Existing Entry

PATCH https://api.gather-grid.com/rest/v1/field_entries?id=eq.<entry_id>

Description: Update an existing field entry. Note that ID fields are immutable and cannot be changed.

Request Body Example:
{
  "entered_value": "New Value for Field"
}
Example Request:
PATCH https://api.gather-grid.com/rest/v1/field_entries?id=eq.456

Headers: Same as above for write operations.

D. Soft Deleting Data (PATCH Requests)

For soft deletes (updating the active flag), include the header:

Content-Profile: YOUR_TENANT_ID

Include Accept-Profile: YOUR_TENANT_ID if expecting a response.

Mark an Entry as Inactive

PATCH https://api.gather-grid.com/rest/v1/entries?id=eq.<entry_id>

Description: Instead of permanently deleting an entry, update its active flag to false to mark it as inactive.

Request Body Example:
{
  "active": false
}
Example Request:
PATCH https://api.gather-grid.com/rest/v1/entries?id=eq.456

Headers: Same as above for write operations.

3. Query Parameters for GET Requests

The API supports common query parameters to help you filter and paginate data:

Filtering:

Retrieve records based on a specific field:

GET /entries?status=eq.completed

Pagination:

Limit the number of records and control the starting point:

GET /entries?limit=10&offset=20

4. Security & Permissions

JWT Authentication:

Every request must include a valid JWT token in the Authorization header. This token ensures that only authorized tenant admins can access and modify data.

API Key:

Your API key must be included in every request.

Tenant Isolation:

The proper use of Accept-Profile (for read) and Content-Profile (for write) ensures that all operations occur in your designated tenant schema.

5. Examples

Example: Retrieve 10 Things

GET https://api.gather-grid.com/rest/v1/things?limit=10

Headers:

apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Accept-Profile: YOUR_TENANT_ID
Content-Type: application/json

Example: Create a New Entry

POST https://api.gather-grid.com/rest/v1/entries

Headers:

apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Content-Type: application/json
Content-Profile: YOUR_TENANT_ID
Accept-Profile: YOUR_TENANT_ID
Prefer: return=representation

Body:

{
  "thing_id": 123
}

Response:

[
  {
    "id": 351,
    "thing_id": 8,
    "classification_item_id": null,
    "classification_item_name": null,
    "validity_start_date": null,
    "validity_end_date": null,
    "created_by": null,
    "created_at": "20250305T034910.74340000",
    "updated_at": "20250305T034910.74340000"
  }
]

Example: Create a Field Entry

POST https://api.gather-grid.com/rest/v1/field_entries

Headers:

apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Content-Type: application/json
Content-Profile: YOUR_TENANT_ID

Body:

{
  "entry_id": 351,
  "field_id": 45,
  "value": "Value for Field 45"
}

Example: Update an Entry

PATCH https://api.gather-grid.com/rest/v1/field_entries?id=eq.456

Body:

{
  "entered_value": "New Value for Field"
}

Headers:

apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Content-Type: application/json
Content-Profile: YOUR_TENANT_ID

Example: Soft Delete an Entry

PATCH https://api.gather-grid.com/rest/v1/entries?id=eq.456

Body:

{
  "active": false
}

Headers:

apikey: YOUR_API_KEY
Authorization: Bearer USER_JWT_TOKEN
Content-Type: application/json
Content-Profile: YOUR_TENANT_ID