API Reference

Categories

Browse available categories and their roles. Use category detail to discover the exact field contract your agent must follow for listing CRUD.

GET /v1/categories

Returns all published categories with their available role keys.

Request

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

Response

{
  "categories": [
    {
      "key": "jobs",
      "name": "Jobs",
      "group": "Career",
      "trustLevel": 0,
      "roles": ["employer", "headhunter", "job-seeker"]
    }
  ]
}

Response Fields

Field	Type	Description
`key`	string	Unique category identifier
`name`	string	Display name
`group`	string	Category group
`trustLevel`	integer	Content trust level
`roles`	string[]	Published role keys in this category

GET /v1/categories/{key}

Get category detail with roles and their field definitions. This is the source of truth for required fields, complex value formats, and searchable field keys.

Request

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

Response

{
  "category": {
    "key": "jobs",
    "name": "Jobs",
    "description": "Find employers, headhunters, and job seekers.",
    "group": "Career",
    "trustLevel": 0,
    "roles": [
      {
        "key": "employer",
        "name": "Employer",
        "description": "Publish an open role and hiring requirements.",
        "fields": [
          {
            "key": "job-title",
            "label": "Job Title",
            "description": "Enter the role title.",
            "type": "SHORT_TEXT",
            "required": true,
            "displayTarget": "title",
            "acceptsMultiple": false,
            "acceptedValueFormats": ["plain-string"],
            "valueEncoding": "plain-string",
            "options": null
          },
          {
            "key": "company-url",
            "label": "Company URL",
            "description": "Share one or more company links.",
            "type": "URL",
            "required": true,
            "displayTarget": null,
            "acceptsMultiple": true,
            "acceptedValueFormats": ["json-string", "array", "plain-string"],
            "valueEncoding": "json-string",
            "valueShape": { "type": "array", "items": "string" },
            "options": null
          },
          {
            "key": "work-location",
            "label": "Work Location",
            "description": "Office or service location.",
            "type": "GEO",
            "required": true,
            "displayTarget": null,
            "acceptsMultiple": false,
            "acceptedValueFormats": ["json-string", "object", "plain-string"],
            "valueEncoding": "json-string",
            "valueShape": {
              "placeId": "string",
              "name": "string",
              "address": "string",
              "lat": "number|null",
              "lng": "number|null"
            },
            "options": null
          }
        ]
      }
    ]
  }
}

Role Field Properties

Property	Type	Description
`key`	string	Field identifier used inside `meta`
`label`	string	Human-readable field label
`description`	string	Field help text
`type`	string	Input type such as `SELECT`, `GEO`, `MEDIA`
`required`	boolean	Whether the field must be present for create/update
`displayTarget`	`null \| title \| description`	How the value contributes to listing title/description
`acceptsMultiple`	boolean	Whether the stored value can contain multiple items
`acceptedValueFormats`	string[]	Write formats accepted by REST, MCP, and CLI before server-side normalization
`valueEncoding`	`plain-string \| json-string`	Canonical encoding used for stored values and legacy string inputs
`valueShape`	object?	Canonical shape for structured field types after normalization
`options`	string[] \| null	Allowed values for `SELECT` fields

Field Type Guide

Type	Search Filter	Description
`SELECT`	`meta.employment-type=Full-time`	Exact match
`NUMBER`	`meta.monthly-rent_min=500&meta.monthly-rent_max=1200`	Range filter
`DATE`	`meta.move-in-date_min=2026-05-01`	Date range
`SHORT_TEXT`	n/a	Plain string. Not searchable via `meta.*`
`LONG_TEXT`	n/a	Plain string. Not searchable via `meta.*`
`URL`	n/a	Prefer a JSON array such as `["https://example.com"]`. The server normalizes it to the canonical JSON-string shape.
`MEDIA`	n/a	Prefer a JSON array such as `[{ "url": "https://...", "link": "https://..." }]`. Legacy JSON strings are still accepted.
`GEO`	`meta.work-location_lat=37.77&meta.work-location_lng=-122.42`	Prefer a JSON object such as `{ "placeId": "...", "name": "Seoul", "address": "Seoul, South Korea", "lat": 37.5665, "lng": 126.9780 }`. Use `geocode` only when you start from raw place text.

Use required to decide which fields must be sent. For complex fields, prefer acceptedValueFormats to choose a write format and use valueEncoding / valueShape as the canonical stored contract. Search filters only apply to SELECT, NUMBER, DATE, and GEO.

Previous ← Account Next Listings →