API Reference

Listings

Search, browse, create, and manage listings on Markidy.

GET /v1/listings/search

Search listings with filters. All parameters are optional.

Query Parameters

Parameter	Type	Description
`q`	string	Search query (optional)
`category`	string	Category key
`role`	string	Role key (requires category)
`country`	string	Country codes, comma-separated (`kr,ja,us`)
`verified`	integer	Verification level (`0`, `1`, `2`)
`sort`	string	`recent` (default), `trust`, `views`, `requests`
`page`	integer	Page number (default: 1)
`pageSize`	integer	Page size (default: 16, max: 50)
`meta.{key}`	string	SELECT field filter
`meta.{key}_min`	string	NUMBER/DATE min value
`meta.{key}_max`	string	NUMBER/DATE max value
`meta.{key}_lat`	number	GEO field latitude (use `GET /v1/geocode` to convert addresses)
`meta.{key}_lng`	number	GEO field longitude

Examples

# Text search with meta filter
curl "https://api.markidy.com/v1/listings/search?q=agent&meta.language=Python&meta.experience_min=3" \
  -H "Authorization: Bearer mk_your_api_key"

# Browse by category with trust sort
curl "https://api.markidy.com/v1/listings/search?category=ai-agent&role=developer&sort=trust" \
  -H "Authorization: Bearer mk_your_api_key"

# GEO proximity search (sorted by distance)
curl "https://api.markidy.com/v1/listings/search?category=education&meta.location_lat=37.77&meta.location_lng=-122.42" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "listings": [
    {
      "id": "clx...",
      "title": "AI Agent Developer with 5 Years of Python Experience",
      "description": "Specializing in chatbots, RAG pipelines...",
      "categoryKey": "ai-agent",
      "categoryName": "AI Agent",
      "roleKey": "developer",
      "roleName": "AI Developer",
      "verifiedLevel": 1,
      "country": "kr",
      "displayName": "John",
      "distanceKm": 3.2,
      "createdAt": "2026-03-15T10:00:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "pageSize": 16
}

Response Fields

Field	Type	Description
`id`	string	Listing ID
`title`	string	Derived from `displayTarget: "title"` field
`description`	string	From `displayTarget: "description"` field
`categoryKey`	string	Category identifier
`categoryName`	string	Category display name
`roleKey`	string	Role identifier
`roleName`	string	Role display name
`verifiedLevel`	integer	Verification level (0–2)
`country`	string	Country code
`displayName`	string	Display name
`createdAt`	string	ISO 8601 timestamp
`distanceKm`	number \| null	Distance in km when GEO filter is active, `null` otherwise

GET /v1/listings/{id}

Get detailed listing information including channel availability and your existing request.

Request

curl https://api.markidy.com/v1/listings/clx123 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "listing": {
    "id": "clx...",
    "title": "AI Agent Developer...",
    "description": "Specializing in chatbots...",
    "categoryKey": "ai-agent",
    "roleKey": "developer",
    "meta": { "experience": "5", "language": "Python" },
    "profile": {
      "displayName": "John",
      "description": "Self-introduction...",
      "verifiedLevel": 1,
      "country": "kr"
    },
    "channels": [
      { "key": "markidy", "available": true },
      { "key": "telegram", "available": true },
      { "key": "discord", "available": false, "reason": "requester_not_connected" }
    ],
    "myRequest": null,
    "createdAt": "2026-03-15T10:00:00Z"
  }
}

channels shows per-requester availability. markidy is Markidy's built-in chat — always available: true when listed. External channels (telegram, discord) require both parties to be connected. myRequest is null if no request has been sent.

Additional Fields (vs Search)

Field	Type	Description
`meta`	object	Dynamic field values
`profile.displayName`	string	Display name
`profile.description`	string	Self-introduction
`profile.verifiedLevel`	integer	Verification level (0–2)
`profile.country`	string	Country code
`channels[].key`	string	Channel identifier
`channels[].available`	boolean	Whether this channel can be used for request
`channels[].reason`	string \| null	`owner_disconnected` — listing owner's channel is inactive. `requester_not_connected` — your API key's account hasn't connected this channel.
`myRequest`	object \| null	Existing request from current user
`myRequest.id`	string	Request ID
`myRequest.status`	string	`PENDING`, `ACCEPTED`, `REJECTED`

GET /v1/listings/mine

List your own listings with optional status filter.

Query Parameters

Parameter	Type	Description
`status`	string	Filter: `ACTIVE`, `PENDING`, `PAUSED`, `REJECTED`
`page`	integer	Page number (default: 1)
`pageSize`	integer	Page size (default: 16)

Response

{
  "listings": [
    {
      "id": "clx...",
      "status": "ACTIVE",
      "categoryKey": "ai-agent",
      "roleKey": "developer",
      "meta": { "experience": "5", "language": "Python" },
      "createdAt": "2026-03-15T10:00:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 16
}

Response Fields

Field	Type	Description
`id`	string	Listing ID
`status`	string	`ACTIVE`, `PENDING`, `PAUSED`, `REJECTED`
`categoryKey`	string	Category identifier
`roleKey`	string	Role identifier
`meta`	object	Dynamic field values
`createdAt`	string	ISO 8601 timestamp

POST /v1/listings

Create a new listing. API-created listings always start as PENDING and require admin approval.

Request Body

Field	Type	Required	Description
`categoryKey`	string	✅	Category key
`roleKey`	string	✅	Role key
`meta`	object	✅	Dynamic field values per role
`channels`	string[]	✅	Channels to receive requests (must be connected)
`webhookIds`	string[]		Webhook IDs to trigger on match requests

Request Body

{
  "categoryKey": "ai-agent",
  "roleKey": "developer",
  "meta": { "experience": "5", "language": "Python" },
  "channels": ["telegram", "discord"],
  "webhookIds": ["wh_abc123"]
}

Response (201)

{
  "id": "clx...",
  "status": "PENDING",
  "createdAt": "2026-03-18T12:00:00Z"
}

Listing creation is rate-limited to 5 per hour per API key. Verified Level 2 accounts get 10 per hour.

PATCH /v1/listings/{id}

Update a listing (partial update). Only include fields you want to change.

Field	Type	Description
`meta`	object	Updated field values, merged with existing
`channels`	string[]	Replaced entirely
`webhookIds`	string[]	Replaced entirely

Updating a listing resets its status to PENDING for re-approval.

PATCH /v1/listings/{id}/status

Pause or resume a listing.

Status	Description
`PAUSED`	Hides from search (only ACTIVE listings)
`ACTIVE`	Resumes a paused listing

Request Body

{ "status": "PAUSED" }

DELETE /v1/listings/{id}

Permanently delete a listing.

Response

{ "id": "clx...", "deleted": true }

Previous ← Categories Next Match Requests →