Idempotency-Key, If-Match, pending operations and the error format. This page uses $CONNECT_API_BASE_URL for the base URL. Ask GRiDD support (support@grdd.net) for the Connect API base URL for your environment.
The core route
GET /api/content/{griddid}/documents is a different, read-only route. See Get Documents.What is available
The Document routes are implemented as owner routes (your own company) and as authenticated reads of another company’s documents. The Connect API README names only Fleets and Vehicles as complete production implementations, and says not to infer completeness for other content types. This page describes the route contracts in the source and does not claim more.Endpoints
Owner routes
These routes act on the company in your token. For an update, rename, visibility change, move or delete,If-Match and Idempotency-Key are both required.
Read the documents of another company
Both routes need your Bearer token. They return a reduced record. See Public record. Query:
locale, force.
A viewer may read a document if one of these is true: its visibility is public; the viewer is the owner; the owner shared it with the viewer in sharewith; its visibility is gnet; or its visibility is partners and core confirms that the viewer is a partner of the owner. The public/{griddid} route returns only public documents.
Folders
Documents can be organized in folders. The folder routes follow the same rules as the document routes. This page lists them without detail.
The folder
PATCH and DELETE routes need If-Match and Idempotency-Key. POST /api/document-folders and the order route need Idempotency-Key.
Not for external use or not described
GET /api/documents/published/{griddid}andGET /api/document-folders/public/{griddid}use theServicecredential of the public website renderer./api/documents/advisor/**andGET /api/document-folders/advisor/{griddid}are for the compliance advisor company only./api/documents/{documentId}/trackingis a document tracking route that depends on an external provider. It is not described here./api/document-media/**(albums and photos) is a separate part of the API. It is not described here.
Authentication and access
- Send
Authorization: Bearer YOUR_ACCESS_TOKEN. See Authentication. - The owner routes do not check a role in the token. A token with the role
ADMINcan read documents of other companies through the viewer rules. - Creating a document has no subscription check in the source at the reviewed commit. The subscription contract sets no limit for document uploads.
Document fields
Read record
Public record
public/{griddid} and partner/{griddid} return these fields only: id, title, griddid, badgeUrl, issueDate, expiryDate, description, documentType, visibility, issuer, folder, sort_order, compliance_status, slug, updatedAt, createdAt. They do not return documentUrl.
Write body
All write bodies are strict. Unknown keys return400 invalid_request.
Create (POST /api/documents):
document accepts the read fields, except id, griddid, slug, createdAt and updatedAt. title is required. It is trimmed and must not be empty. All other fields are optional. If you omit visibility, the API sets it from documentType. For example ein and contract default to private, certificate and ada to public, and insurance_* and permit_airpot to gnet. An unknown or missing type defaults to private.
Update (PATCH /api/documents/{documentId}): the body is { "document": { ... } } with any subset of those fields, plus optional locale and contentLanguage (update_version or add_version).
- A document that a tracking provider manages cannot change
certificialTracking,policyRequestId,issueDateorexpiryDate. The response is422 domain_rejected. - Every
sharewithentry needs agriddid. The IDs must be unique company IDs. Otherwise the response is422 domain_rejected.
PATCH /api/documents/order): body { "documents": [{ "id": 41, "sortOrder": 1, "version": 1, "folderId": null }], "locale": "en" }. At least one document. The IDs must be unique. folderId is optional.
Create a document record
The body is the fixturedocument-create.json:
201 Created (or 202 if pending) with an ETag. The body has status, data (the document), effects and invalidated, and can have operationId.
Upload a file
POST /api/documents/upload takes multipart/form-data with exactly two parts: file and metadata. Other parts return 400 invalid_request.
fileis the file. The maximum size is 10 MiB. The allowed formats are PDF, PNG, JPG/JPEG, WEBP, DOCX, DOC, XLS, XLSX, CSV and ZIP. The API checks the file extension and the first bytes of the file. A file that does not match returns415 unsupported_media_type, and one that is too large returns413 payload_too_large.metadatais a JSON string with the same fields as the create body (document,locale,contentLanguage). To replace the file of an existing document, adddocumentIdandexpectedVersion.
201 for a new document, 200 when a file is replaced, and 202 when pending. Do not set the Content-Type header yourself. The client must add the multipart boundary.
Read documents
200 with the header ETag: "v1". This is the fixture document-record.json:
GET /api/documents returns { "items": [...], "meta": {...} }. The list has no pagination parameters. Query: locale and force.
A document of another company returns 404 not_found on the owner routes.
GET /api/documents/public/demo-company returns the reduced record. This is the fixture document-public-list.json:
Update a document
200 OK with the header ETag: "v2". This is the fixture document-mutation.json:
202 with status: "pending" and an operationId. A stale If-Match returns 412 version_conflict.
Download a document
documentUrl is not a download link. To download a document, ask for a signed URL. ownerGriddid is the company that owns the document:
document-signed-read.json:
403 forbidden. If the document does not exist or has no file, the response is 404 not_found.
Delete a document
204 No Content when the delete is complete. If follow-up work is not finished, the response is 202 with status: "pending", data: null, operationId and effects.