Endpoints

The complete v1 API reference. Every endpoint is served under the API base and authenticated with a Bearer access token.

Base URL & authentication

All endpoints live under https://api.zetpin.com/dev/v1 and require a valid zpat_ access token passed in the Authorization header. Each endpoint also requires a specific scope — shown on the right of every card below.

http

Authorization: Bearer zpat_9f8e7d6c...

Get the authorizing user

GET/dev/v1/mescope: profile.read

Returns the profile of the user who authorized your app.

bash

curl https://api.zetpin.com/dev/v1/me \
  -H "Authorization: Bearer zpat_9f8e7d6c..."

json

{
  "id": "usr_7hk2...",
  "name": "Aditi Rao",
  "photoUrl": "https://cdn.zetpin.com/u/7hk2.jpg",
  "karma": 428,
  "neighborhood": "Indiranagar, Bengaluru"
}

Publish a post

POST/dev/v1/postsscope: posts.write

Publishes a post to the user's neighborhood and returns a public permalink.

Body parameters (JSON) — you must supply at least one of title, content, or images:

Field	Type	Notes
`title`	string?	Optional headline.
`content`	string?	Post body text.
`type`	string?	Post type / category.
`images`	string[]?	Image URLs.
`tags`	string[]?	Topic tags.
`latitude`, `longitude`	number?	Post location. Falls back to the user's saved neighborhood when omitted.
`reachKm`	number?	Hyperlocal reach radius in kilometres.
`visibility`	string?	Who can see the post.

bash

curl -X POST https://api.zetpin.com/dev/v1/posts \
  -H "Authorization: Bearer zpat_9f8e7d6c..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Fresh sourdough at the Saturday market ☀️",
    "tags": ["food", "market"],
    "reachKm": 3,
    "visibility": "public"
  }'

json

// 201 Created
{
  "id": "post_a1b2c3",
  "content": "Fresh sourdough at the Saturday market ☀️",
  "tags": ["food", "market"],
  "reachKm": 3,
  "visibility": "public",
  "permalink": "https://zetpin.com/post/post_a1b2c3",
  "createdAt": "2026-07-08T09:14:22.000Z"
}

Monthly quota

Publishing is metered per app. Past your app's monthly quota (default 100/month) this endpoint returns 429 quota_exceeded. See Rate limits & quotas.

List the user's posts

GET/dev/v1/postsscope: posts.read

Returns the authorizing user's own posts, paginated.

Query parameters: page (default 1) and limit (max 50). The response includes a meta object with page, limit, and total.

bash

curl "https://api.zetpin.com/dev/v1/posts?page=1&limit=20" \
  -H "Authorization: Bearer zpat_9f8e7d6c..."

json

{
  "data": [
    {
      "id": "post_a1b2c3",
      "content": "Fresh sourdough at the Saturday market ☀️",
      "permalink": "https://zetpin.com/post/post_a1b2c3",
      "createdAt": "2026-07-08T09:14:22.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1 }
}

Get a single post

GET/dev/v1/posts/:idscope: posts.read

Returns one of the user's own posts. Returns 404 if the post isn't theirs or doesn't exist.

bash

curl https://api.zetpin.com/dev/v1/posts/post_a1b2c3 \
  -H "Authorization: Bearer zpat_9f8e7d6c..."

json

{
  "id": "post_a1b2c3",
  "content": "Fresh sourdough at the Saturday market ☀️",
  "tags": ["food", "market"],
  "reachKm": 3,
  "visibility": "public",
  "permalink": "https://zetpin.com/post/post_a1b2c3",
  "createdAt": "2026-07-08T09:14:22.000Z"
}

Get post analytics

GET/dev/v1/posts/:id/analyticsscope: analytics.read

Returns engagement metrics for one of the user's posts.

bash

curl https://api.zetpin.com/dev/v1/posts/post_a1b2c3/analytics \
  -H "Authorization: Bearer zpat_9f8e7d6c..."

json

{
  "id": "post_a1b2c3",
  "likes": 47,
  "comments": 12,
  "publishedAt": "2026-07-08T09:14:22.000Z",
  "permalink": "https://zetpin.com/post/post_a1b2c3"
}

Delete a post

DELETE/dev/v1/posts/:idscope: posts.write

Soft-deletes one of the user's own posts.

bash

curl -X DELETE https://api.zetpin.com/dev/v1/posts/post_a1b2c3 \
  -H "Authorization: Bearer zpat_9f8e7d6c..."

json

{ "id": "post_a1b2c3", "deleted": true }

PreviousRefreshing & revoking Next Errors