Posts API

The Posts API lets your backend manage your company’s posts on the GNet network with authenticated calls. It uses the same validation, plan checks, rate limits, trust scoring, moderation routing, and post storage as the Connect portal. There is no multi-step handshake or impersonation exchange: get a Bearer token, then call the door you need. All five doors are owner-scoped.

Verb	Path	Does
`POST`	`/api/partner/posts`	Create a post.
`GET`	`/api/partner/posts?limit=&cursor=`	List your own posts, newest first.
`GET`	`/api/partner/posts/{id}`	Read one owned post in any status, including `archived`.
`PATCH`	`/api/partner/posts/{id}`	Apply a strict partial revision to one owned post.
`DELETE`	`/api/partner/posts/{id}`	Retire (archive) one owned post; this is not hard deletion.

All five methods run on the Connect application host (dashboard.grdd.net), not on core.grdd.net. Use https://dashboard.grdd.net in production and https://dashboard.grdd.dev in the development environment. Every method requires a Bearer token issued by GNet core.

Authentication and ownership

To obtain a token, see the Get Token API. Send the token in the standard header on every request:

Authorization: Bearer <access_token>

The partner surface is owner-scoped. A caller can read, revise, or retire only posts owned by the token’s authorized company; a griddid supplied in a create body must be the caller’s own GNET ID (or the authorized parent account). There is no partner-side admin override or act-on-behalf-of mode. Authentication failures are the same for every door:

Status	`error`	Meaning
`401`	`missing_token`	No `Authorization: Bearer` header was supplied.
`401`	`invalid_token`	Core rejected the token or its verification response was invalid.
`401`	`expired_token`	The token has expired; request a fresh token.
`502`	`core_unreachable`	The Connect application could not verify the token with core; retry later.

Create a post

The create door publishes a post to the GNet network on behalf of your own company, with a single authenticated call. It produces the same result as creating the post inside the Connect portal — the same validation, plan check, rate limits, trust scoring and moderation routing, in the same order.

Endpoint

POST https://dashboard.grdd.net/api/partner/posts

Authentication and headers

Authorization: Bearer <access_token>
Content-Type: application/json
Idempotency-Key: <unique string>   (optional, recommended)

You may only create posts for your own company. The griddid in the body must match the GNET ID your token was issued for (or its parent account); anything else is rejected with 403 not_entitled. There is no impersonation or act-on-behalf-of mode.

Request body

{
  "griddid": "acmelimo",
  "detail": {
    "postType": "update",
    "visibility": "gnet",
    "status": "draft",
    "slug": "pending",
    "title": "New airport shuttle route now live",
    "summary": "Daily LAX ↔ Long Beach service starting August 1.",
    "body": "Full post text here…",
    "imageUrls": ["https://your-cdn.example.com/shuttle.jpg"],
    "ctaUrl": "https://acmelimo.com/shuttle",
    "ctaLabel": "See schedule"
  },
  "logoUrl": "https://your-cdn.example.com/logo.png",
  "countryCode": "US"
}

Top-level fields

Field	Type	Required	Notes
`griddid`	string	Yes	Your GNET ID. Must match your token’s company.
`detail`	object	Yes	The post itself — see below.
`logoUrl`	string (URL)	No	Defaults to your company logo on file.
`countryCode`	string (2 chars)	No	Defaults to your company’s country.

`detail` fields

Field	Type	Required	Notes
`postType`	enum	Yes	See post types.
`visibility`	enum	Yes	`public` \| `gnet` \| `partners`. May be downgraded — see visibility.
`status`	enum	No	Defaults to `draft`, then is server-assigned — see what the server overrides. Sending `draft` is recommended.
`slug`	string	Yes	Send any placeholder (for example, `"pending"`). Server-generated from the title.
`title`	string	Yes	5–150 characters.
`summary`	string	No	Max 300 characters.
`body`	string	No	Max 4096 characters.
`imageUrls`	string[] (URL)	No	Max 4. Must be already-hosted absolute URLs — see images.
`imageUrl`	string (URL)	No	Single-image legacy field.
`ctaUrl`	string	No	Absolute URL, or a site-relative path starting with `/`.
`ctaLabel`	string	No	Max 80 characters.
`category`	string	No
`iconKey`	string	No
`sourceName`	string	No	Max 120 characters.
`sourceLogoUrl`	string (URL)	No
`eventDate`	string	No
`eventLocation`	string	No	Max 200 characters.
`expiresAt`	string	No
`pinnedUntil`	string	No
`isSticky`	boolean	No
`locales`	object	No	Per-language overrides keyed `en` / `fr` / `de` / `es`, each accepting `title`, `summary`, `body`, `ctaLabel`.
`translateOptOut`	boolean	No	Skip auto-translation.
`typed`	object	Conditional	Required for some post types — see below.

Post types

postType must be one of:

Post type	Rate cap	Default visibility	`typed` required
`update`	5 / day	`gnet`	—
`capacity_available`	3 / day	`partners`	✅
`press_release`	2 / week	`public`	—
`hiring`	2 / week	`public`	✅
`fleet_for_sale`	3 / week	`public`	✅
`event`	3 / week	`gnet`	✅
`ask_network`	5 / week	`gnet`	✅
`case_study`	1 / week	`public`	—

Exceeding a cap returns 429 rate_limited with a Retry-After header.

`typed` fields

Five post types require a detail.typed object. A missing or invalid typed block fails validation with 422.

"typed": {
  "routeFrom": "Los Angeles",     // required, max 120
  "routeTo": "Las Vegas",         // required, max 120
  "startDate": "2026-08-01",      // required
  "endDate": "2026-08-14",        // optional
  "vehicleType": "SPRINTER"       // optional, max 80
}

"typed": {
  "role": "Chauffeur — Nights",           // required, max 120
  "location": "Palm Beach, FL",           // optional, max 120
  "applyUrl": "https://acmelimo.com/jobs" // optional, must be a URL
}

"typed": {
  "vehicleRef": "2021 Mercedes Sprinter", // required, max 120
  "year": 2021,                           // optional, integer 1950–2100
  "price": "$68,000",                     // optional, max 40
  "location": "Palm Beach, FL"            // optional, max 120
}

"typed": {
  "eventDate": "2026-09-12",                       // required
  "eventLocation": "Las Vegas Convention Center",  // optional, max 200
  "registrationUrl": "https://example.com/reg"     // optional, must be a URL
}

"typed": {
  "question": "Anyone running SUVs out of SNA on weekends?", // required, max 500
  "topicTags": ["airport", "suv"]                            // optional, max 8 tags
}

What the server overrides

These three output fields are decided by the server — send placeholders where the create schema asks for them and read the real values back from the response:

status — always recomputed. Companies flagged as post-trusted publish immediately (published); everyone else is queued for moderator review (pending_review). You cannot self-publish by sending "status": "published".
slug — always regenerated from your title, scoped to your GNET ID.
authorTrustAtPublish — computed from your profile score, partner count, plan tier and account age.

Visibility

If you request "visibility": "public" but your trust score is below the public-visibility floor, the post is accepted and downgraded to gnet. When this happens the response includes "visibilityDowngraded": true.

Images

There is no partner image-upload endpoint. Host your images yourself and pass absolute URLs in imageUrls (maximum 4).

Create request example

curl -X POST \
  'https://dashboard.grdd.net/api/partner/posts' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f1c2e64-1f2a-4c8e-9d3b-6a7f5e1c2d90' \
  -d '{
    "griddid": "acmelimo",
    "detail": {
      "postType": "update",
      "visibility": "gnet",
      "status": "draft",
      "slug": "pending",
      "title": "New airport shuttle route now live",
      "summary": "Daily LAX to Long Beach service starting August 1.",
      "body": "We are adding two daily runs…"
    }
  }'

Create response

`201 Created` — published immediately

{
  "ok": true,
  "id": "0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90",
  "slug": "new-airport-shuttle-route-now-live",
  "status": "published",
  "visibilityDowngraded": false
}

`202 Accepted` — queued for review

{
  "ok": true,
  "id": "0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90",
  "slug": "new-airport-shuttle-route-now-live",
  "status": "pending_review",
  "visibilityDowngraded": false
}

202 means the post was created but is not visible yet — a GNet moderator must approve it. Poll GET /api/partner/posts/{id} to read the current post.detail.status; it will show published when the post is approved. This API sends no callback or webhook on approval.

Every response carries an ok boolean. Never treat a 2xx-shaped body as success without checking it.

Create errors

Status	`error`	Meaning
`400`	`bad_request`	Body cannot be parsed as JSON, or JSON parsing produces `null`/a primitive; other invalid shapes fail schema validation.
`401`	`missing_token`	No `Authorization: Bearer` header.
`401`	`invalid_token`	Token rejected by core.
`401`	`expired_token`	Token expired — request a new one.
`403`	`not_entitled`	`griddid` is not your token’s company.
`403`	`plan_required`	Your Connect plan or trial does not allow posting.
`404`	`operator_not_found`	The GNET ID could not be resolved.
`409`	`idempotency_conflict`	Same `Idempotency-Key` reused with a different body.
`422`	`validation_error`	Payload failed schema validation; `details` carries the field-level errors.
`429`	`rate_limited`	Rate cap for this post type reached; `details.resetsAt` is an epoch-ms timestamp and a `Retry-After` header is set.
`500`	`internal_error`	Unexpected server error.
`502`	`core_unreachable`	Token verification upstream failed — retry later.

{
  "ok": false,
  "error": "validation_error",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "detail.title": ["String must contain at least 5 character(s)"]
    }
  }
}

Retrying safely

Pass an Idempotency-Key header — any unique string per logical post, such as a UUID you generate before the first attempt.

Same key, same body → replays the original response instead of creating a second post.
Same key, different body → 409 idempotency_conflict.
Keys are scoped to your caller identity and expire after 24 hours.

Without an idempotency key, a network timeout followed by a retry can create duplicate posts.

List your posts

The collection door returns the caller’s own inventory, newest first. It has no status or visibility filter, so active posts in draft, pending_review, scheduled, or published status can be returned. Retired/archived posts are excluded because retiring a post removes it from this list’s author index.

Endpoint

GET https://dashboard.grdd.net/api/partner/posts?limit=20&cursor=1732000000000 Omit both query parameters for the first page. Use the nextCursor from one response as the cursor on the next request. A null nextCursor means the last page.

Authentication and headers

Authorization: Bearer <access_token>

Query parameters

Parameter	Type	Default / limit	Notes
`limit`	positive integer	Default `20`, maximum `100`	Values above `100` are capped at `100`. A missing, non-numeric, or non-positive value uses the default.
`cursor`	integer	None	Use the numeric `nextCursor` returned by the previous page. A missing or non-numeric value starts at the newest post.

The cursor is an exclusive created-at cursor. The API returns posts in descending created-at order, and nextCursor is a number when another page exists.

Request shape

The collection GET has no request body.

Request example

curl 'https://dashboard.grdd.net/api/partner/posts?limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

{
  "ok": true,
  "posts": [
    {
      "id": "0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90",
      "griddid": "acmelimo",
      "companyName": "Acme Limo",
      "detail": {
        "postType": "update",
        "visibility": "gnet",
        "status": "pending_review",
        "slug": "new-airport-shuttle-route-now-live",
        "title": "New airport shuttle route now live",
        "summary": "Daily LAX to Long Beach service starting August 1.",
        "body": "We are adding two daily runs…"
      },
      "createdAt": 1732000000000,
      "updatedAt": 1732000000000,
      "logoUrl": "https://cdn.example.com/acmelimo/logo.png",
      "countryCode": "US"
    }
  ],
  "nextCursor": 1731900000000
}

posts contains MemberPost records, including their current status. If the page is the last page, the same response has "nextCursor": null.

Errors

Status	Body	Meaning
`200`	`{ "ok": true, "posts": [...], "nextCursor": number \| null }`	The caller’s own page of posts.
`401`	`{ "ok": false, "error": "missing_token" \| "invalid_token" \| "expired_token" }`	Authentication failed; see authentication.
`403`	`{ "ok": false, "error": "not_entitled" }`	The verified caller has no authorized owner identity for the list.
`500`	`{ "ok": false, "error": "internal_error" }`	Listing or its storage read failed unexpectedly.
`502`	`{ "ok": false, "error": "core_unreachable" }`	Core token verification was unavailable.

Read one post

Use the item read door to inspect one post you own in any status, including archived. This is the status-polling door: after a create returns pending_review, poll this endpoint to see whether post.detail.status is now published. After retirement, use it to confirm that the status is archived; the record remains readable even though it no longer appears in the collection list.

Endpoint

GET https://dashboard.grdd.net/api/partner/posts/{id} Replace {id} with the id returned by the create or collection response.

Authentication and headers

Authorization: Bearer <access_token>

Request shape

The item GET has no request body. The post ID is supplied in the URL path.

Request example

curl 'https://dashboard.grdd.net/api/partner/posts/0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

{
  "ok": true,
  "post": {
    "id": "0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90",
    "griddid": "acmelimo",
    "companyName": "Acme Limo",
    "detail": {
      "postType": "update",
      "visibility": "gnet",
      "status": "pending_review",
      "slug": "new-airport-shuttle-route-now-live",
      "title": "New airport shuttle route now live",
      "summary": "Daily LAX to Long Beach service starting August 1.",
      "body": "We are adding two daily runs…"
    },
    "createdAt": 1732000000000,
    "updatedAt": 1732000000000,
    "logoUrl": "https://cdn.example.com/acmelimo/logo.png",
    "countryCode": "US"
  }
}

The same shape is returned after retirement, with post.detail.status: "archived".

Errors

Status	Body	Meaning
`200`	`{ "ok": true, "post": MemberPost }`	The owned post, in its current status.
`401`	`{ "ok": false, "error": "missing_token" \| "invalid_token" \| "expired_token" }`	Authentication failed; see authentication.
`403`	`{ "ok": false, "error": "not_entitled" }`	The post belongs to another operator. Ownership failures are not masked as `404`.
`404`	`{ "ok": false, "error": "post_not_found" }`	No post record exists for this ID.
`500`	`{ "ok": false, "error": "internal_error" }`	The post read failed unexpectedly.
`502`	`{ "ok": false, "error": "core_unreachable" }`	Core token verification was unavailable.

Revise one post

The revision door applies an allow-listed, strict partial update to one owned post. It does not replace the full post: send only the fields that should change.

Endpoint

PATCH https://dashboard.grdd.net/api/partner/posts/{id}

Authentication and headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request shape

The request must contain a detail object. The revision schema is .partial().strict().refine(non-empty): every field is optional, at least one field is required, and unknown keys inside detail return 422 validation_error instead of being silently dropped.

{
  "detail": {
    "title": "A corrected headline",
    "summary": "Updated summary",
    "body": "Updated post text…",
    "imageUrls": ["https://cdn.example.com/shuttle-new.jpg"],
    "ctaUrl": "https://acmelimo.com/shuttle",
    "locales": {
      "en": { "title": "A corrected headline" }
    }
  }
}

Allow-listed revision fields

The table below is the complete revision shape — no other field can be set through this door.

Field	Notes
`title`	5–150 characters. Changing it regenerates the slug.
`summary`	Max 300 characters.
`body`	Max 4096 characters.
`visibility`	Allowed by the schema, but a different value is refused with `403 visibility_locked`; sending the stored value is a no-op.
`imageUrl`	URL or empty string.
`imageUrls`	Up to 4 absolute URLs.
`ctaUrl`	Absolute URL, empty string, or a site-relative path beginning with `/`.
`ctaLabel`	Max 80 characters.
`category`	String.
`iconKey`	String.
`sourceName`	Max 120 characters.
`sourceLogoUrl`	URL or empty string.
`eventDate`	String.
`eventLocation`	Max 200 characters.
`locales`	`en`, `fr`, `de`, and `es` localized title, summary, body, and CTA label overrides.
`translateOptOut`	Boolean.
`typed`	A typed object; when the stored `postType` requires typed fields, the merged post must satisfy that type’s complete schema. See `typed` fields.

These fields are not in the revision shape: status, slug, postType, expiresAt, pinnedUntil, isSticky, authorTrustAtPublish, and moderationNote. Sending any of them as top-level keys inside detail is a 422, not a silent no-op. Ownership always comes from the stored post; a top-level griddid is rejected with 400 bad_request.

Revision rules

The post must belong to the bearer caller. Another operator receives 403 not_entitled.
The caller’s Connect plan or free trial must allow posting. Otherwise the response is 403 plan_required.
visibility is locked. Sending the same stored value parses successfully and leaves visibility unchanged; sending a different value returns 403 visibility_locked.
Changing title generates a new slug. The old slug resolves through a 30-day redirect. A revision that does not change the title leaves the slug untouched.
An archived post is read-only and refuses every revision with 409 post_archived.
Revising a pending_review post keeps its current status; it does not create a second post or change the moderation state.

Request example

curl -X PATCH \
  'https://dashboard.grdd.net/api/partner/posts/0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "detail": {
      "title": "New airport shuttle route now live — updated"
    }
  }'

Response

{
  "ok": true,
  "id": "0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90",
  "slug": "new-airport-shuttle-route-now-live-updated",
  "status": "pending_review"
}

Errors

Status	Body	Meaning
`200`	`{ "ok": true, "id": string, "slug": string, "status": string }`	Revision applied. The slug changes only when `title` changes.
`400`	`{ "ok": false, "error": "bad_request" }`	Body cannot be parsed as JSON, or JSON parsing produces `null`/a primitive; a top-level `griddid` is also rejected.
`401`	`{ "ok": false, "error": "missing_token" \| "invalid_token" \| "expired_token" }`	Authentication failed; see authentication.
`403`	`{ "ok": false, "error": "not_entitled" }`	The post belongs to another operator.
`403`	`{ "ok": false, "error": "plan_required" }`	The caller’s Connect plan or free trial does not allow posting.
`403`	`{ "ok": false, "error": "visibility_locked" }`	The revision tried to change `visibility` to a different value.
`404`	`{ "ok": false, "error": "post_not_found" }`	No post record exists for this ID.
`404`	`{ "ok": false, "error": "operator_not_found" }`	The owned post’s company profile could not be resolved for the plan check.
`409`	`{ "ok": false, "error": "post_archived" }`	The post was retired and is read-only.
`422`	`{ "ok": false, "error": "validation_error", "details": object }`	An unknown key, empty revision, out-of-range value, or typed object that fails the stored post’s schema.
`500`	`{ "ok": false, "error": "internal_error" }`	Unexpected server error.
`502`	`{ "ok": false, "error": "core_unreachable" }`	Core token verification was unavailable.

Retire one post

The retirement door is an idempotent archive operation, not hard deletion. It accepts a post in any status, including draft, pending_review, scheduled, published, or archived. The post record remains available to the item read door; the retired post is removed from the feed and collection index.

Endpoint

DELETE https://dashboard.grdd.net/api/partner/posts/{id}

Authentication and headers

Authorization: Bearer <access_token>

Request shape

The request has no body. Supply the post ID in the URL path.

Request example

curl -X DELETE \
  'https://dashboard.grdd.net/api/partner/posts/0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

{
  "ok": true,
  "id": "0f3b8c6e-8b41-4f0a-9a2f-1d6c5b4e7a90",
  "status": "archived"
}

A repeat call for an already archived post returns the same 200 body and is safe to retry. The route does not hard-delete post:{id}; the stored record is retained for its two-year TTL, while its feed and author-list indices are removed.

Errors

Status	Body	Meaning
`200`	`{ "ok": true, "id": string, "status": "archived" }`	Archived now, or already archived; repeats are idempotent.
`401`	`{ "ok": false, "error": "missing_token" \| "invalid_token" \| "expired_token" }`	Authentication failed; see authentication.
`403`	`{ "ok": false, "error": "not_entitled" }`	The post belongs to another operator.
`404`	`{ "ok": false, "error": "post_not_found" }`	No post record exists for this ID.
`500`	`{ "ok": false, "error": "internal_error" }`	Unexpected server error.
`502`	`{ "ok": false, "error": "core_unreachable" }`	Core token verification was unavailable.

Usage examples

JavaScript/Node.js

const response = await fetch(
  "https://dashboard.grdd.net/api/partner/posts",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      griddid: "acmelimo",
      detail: {
        postType: "update",
        visibility: "gnet",
        status: "draft",
        slug: "pending",
        title: "New airport shuttle route now live",
        summary: "Daily LAX to Long Beach service starting August 1.",
      },
    }),
  },
);

const result = await response.json();
if (!result.ok) {
  throw new Error(`${response.status} ${result.error}`);
}
console.log(result.status === "published" ? "Live" : "Awaiting review");
console.log("Post ID:", result.id, "slug:", result.slug);

Python

import uuid
import requests

url = "https://dashboard.grdd.net/api/partner/posts"
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
}
payload = {
    "griddid": "acmelimo",
    "detail": {
        "postType": "update",
        "visibility": "gnet",
        "status": "draft",
        "slug": "pending",
        "title": "New airport shuttle route now live",
        "summary": "Daily LAX to Long Beach service starting August 1.",
    },
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

if not result.get("ok"):
    raise RuntimeError(f"{response.status_code} {result.get('error')}")

print("Post ID:", result["id"])
print("Status:", result["status"])

​Posts API

​Authentication and ownership

​Create a post

​Endpoint

​Authentication and headers

​Request body

​Top-level fields

​detail fields

​Post types

​typed fields

​What the server overrides

​Visibility

​Images

​Create request example

​Create response

​201 Created — published immediately

​202 Accepted — queued for review

​Create errors

​Retrying safely

​List your posts

​Endpoint

​Authentication and headers

​Query parameters

​Request shape

​Request example

​Response

​Errors

​Read one post

​Endpoint

​Authentication and headers

​Request shape

​Request example

​Response

​Errors

​Revise one post

​Endpoint

​Authentication and headers

​Request shape

​Allow-listed revision fields

​Revision rules

​Request example

​Response

​Errors

​Retire one post

​Endpoint

​Authentication and headers

​Request shape

​Request example

​Response

​Errors

​Usage examples

​JavaScript/Node.js

​Python

Posts API

Authentication and ownership

Create a post

Endpoint

Authentication and headers

Request body

Top-level fields

`detail` fields

Post types

`typed` fields

What the server overrides

Visibility

Images

Create request example

Create response

`201 Created` — published immediately

`202 Accepted` — queued for review

Create errors

Retrying safely

List your posts

Endpoint

Authentication and headers

Query parameters

Request shape

Request example

Response

Errors

Read one post

Endpoint

Authentication and headers

Request shape

Request example

Response

Errors

Revise one post

Endpoint

Authentication and headers

Request shape

Allow-listed revision fields

Revision rules

Request example

Response

Errors

Retire one post

Endpoint

Authentication and headers

Request shape

Request example

Response

Errors

Usage examples

JavaScript/Node.js

Python