Using the Desk APIPro

Authenticate with your credential in the Authorization header:

Authorization: Bearer odsk_live_...

Articles belong to a category. Create or list categories first, then create articles with categoryId or categorySlug (optionally createCategoryIfMissing: true).

A typical migration workflow:

• 1. Create categories (POST /api/v1/categories) or reuse existing ones
• 2. Upload screenshots (POST /api/v1/assets) and embed the returned URL in HTML
• 3. Bulk upsert drafts with POST /api/v1/articles/bulk (or create one-by-one); use dryRun: true to validate first
• 4. Search including drafts with GET /api/v1/search?q=...&status=all
• 5. Publish when ready (or set status: "published" / publish: true in bulk if you have Publisher)

Categories:

• GET /api/v1/categories — list
• POST /api/v1/categories — create { "title": "Billing", "description": "..." }
• GET /api/v1/categories/:id — get one
• PATCH /api/v1/categories/:id — rename, description, status, sortOrder
• PATCH /api/v1/categories — reorder { "order": ["cat_1", "cat_2"] }
• DELETE /api/v1/categories/:id — delete if empty (Publisher)

Articles:

• GET /api/v1/articles?status=draft&limit=50&offset=0 — list with pagination (status, categoryId, q, sort)
• GET /api/v1/articles/:id — includes adminUrl, previewUrl, publicUrl
• POST /api/v1/articles — create draft (categoryId or categorySlug)
• POST /api/v1/articles/bulk — upsert up to 50 articles by slug (dryRun supported)
• PATCH /api/v1/articles/:id — update fields including slug (old slug kept as an alias when published)
• POST /api/v1/articles/:id/publish / .../archive

Search & assets:

• GET /api/v1/search?q=query&status=all — search drafts and published (default all)
• POST /api/v1/assets — multipart image upload (file, optional articleId); returns url for bodyHtml

Support reasons (contact form topics):

• GET /api/v1/support-reasons — nested dropdown tree + flat ticketCategories
• PUT /api/v1/support-reasons — replace tree ({ "supportReasons": [ ... ] })
• Each reason supports label, instructions, allowTicket, articleIds / articleSlugs, and nested children

Errors return JSON like { "error": { "code": "VALIDATION_ERROR", "message": "..." } }.

Writer can create/update categories, articles, and support reasons. Publisher can publish, archive, upload assets, and delete empty categories. See the Developers page for curl examples.