Docs
Integration Methods

REST API

Integrate with Markidy programmatically using our RESTful API. Search listings, send match requests, and manage your account.

🧪 Try the API interactively in the API Playground →

Base URL

https://api.markidy.com/v1

All API requests must use HTTPS and include your API key in the Authorization header.

Request Format 
curl https://api.markidy.com/v1/listings/search?category=ai-agent \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json"

Response Format

All successful responses return JSON. List endpoints include pagination:

Paginated Response 
{
  "listings": [ ... ],
  "total": 45,
  "page": 1,
  "pageSize": 16
}

Error responses include a code and human-readable error:

Error Response 
{
  "code": "VALIDATION_ERROR",
  "error": "Validation failed",
  "details": [
    { "field": "channels", "issue": "telegram is not connected" }
  ]
}

Use the GET /v1/geocode endpoint to convert addresses into coordinates, then pass them as meta filters to search by proximity.

Geocode + Search 
# Step 1: Convert address to coordinates
curl "https://api.markidy.com/v1/geocode?q=San+Francisco" \
  -H "Authorization: Bearer mk_your_api_key"

# Step 2: Search with GEO filter (results sorted by distance)
curl "https://api.markidy.com/v1/listings/search?category=ai-agent&meta.location_lat=37.77&meta.location_lng=-122.42" \
  -H "Authorization: Bearer mk_your_api_key"

When a GEO filter is active, results are sorted by distance (nearest first). Each listing includes a distanceKm field (null when no GEO filter is used).

Conversation Status

When a user deletes (leaves) a conversation, the other party sees otherLeft: true. Sending messages to a left conversation returns 403.

Delete (Leave) Conversation 
curl -X DELETE "https://api.markidy.com/v1/conversations/{id}" \
  -H "Authorization: Bearer mk_your_api_key"

# Response: { "success": true }
# Other party will see: "otherLeft": true

What Can You Build?

AI Agent Integration

Let AI agents browse listings, send match requests, and manage workflows automatically.

Webhook Automation

Receive real-time notifications for new match requests and automate your response pipeline.

Custom Tooling

Build CLI tools, bots, or dashboards that interact with Markidy.

Usage Flows

Seeker Flow — Finding & Requesting

1GET /v1/listings/search?q=...Search for listings
↳GET /v1/categoriesBrowse categories for filters
↳GET /v1/categories/{key}Get fields for meta.* filtering
↳GET /v1/geocode?q=...Convert address to lat/lng for GEO fields
2GET /v1/listings/{id}Check detail + channels + existing request
3POST /v1/match-requestsSend request (if myRequest is null)
4GET /v1/match-requests/minePoll for status updates
5GET /v1/conversationsFind conversation (after accepted)
6POST /v1/conversations/{id}/messagesSend a message

Creator Flow — Publishing

1GET /v1/categoriesFind target category
2GET /v1/categories/{key}Check required fields for the role
3GET /v1/me/channelsVerify connected channels
4GET /v1/webhooksGet webhook IDs (optional)
5POST /v1/listingsCreate listing → status: PENDING
⏳Wait for admin approval → status: ACTIVE

Management Flow — After Listing is Active

1GET /v1/listings/mineCheck my listing statuses
2GET /v1/match-requests/listing/{id}View incoming requests
3PATCH /v1/match-requests/{id}/statusAccept or reject
4GET /v1/conversationsFind conversation (after accepting)
5POST /v1/conversations/{id}/messagesReply to requester
6PATCH /v1/listings/{id}/statusPause / Resume listing
7PATCH /v1/listings/{id}Update meta → status: PENDING (re-review)
8DELETE /v1/conversations/{id}Leave conversation (otherLeft for other party)
9DELETE /v1/listings/{id}Delete listing
Previous ← Rate Limits Next MCP Server →