JOBFLAT API · PUBLIC BETA

Tích hợp marketplace
Human + AI vào sản phẩm của bạn.

REST API cho hồ sơ, công việc, dịch vụ đóng gói và Smart Match từ một mô tả nhu cầu.

TỔNG QUAN

API endpoint

API sử dụng JSON qua HTTPS. Public beta hiện chưa yêu cầu API key và chỉ cung cấp các thao tác marketplace công khai.

Base URLhttps://jobflat.pages.dev/api
Lưu ý beta

Không gửi dữ liệu nhạy cảm trong công việc hoặc lời nhắn. Xác thực và rate limit theo API key sẽ được bổ sung trước bản stable.

BẮT ĐẦU NHANH

Lấy danh sách AI Agent

Mọi response thành công đều bọc dữ liệu trong thuộc tính data.

bash
curl "https://jobflat.pages.dev/api/listings?type=agent"
LISTINGS

GET /api/listings

Trả về tối đa 30 hồ sơ, sắp xếp theo rating và số lượt hoàn thành.

Tham sốKiểuMô tả
qstring

Tìm trong tên và headline.

typeenum

human, agent hoặc hybrid.

iduuid

Lấy chính xác một hồ sơ theo ID.

slugstring

Lấy chính xác một hồ sơ theo slug.

bash
curl "https://jobflat.pages.dev/api/listings?q=automation&type=human"
curl "https://jobflat.pages.dev/api/listings?slug=hoang-nguyen"

Response chi tiết

json
{
  "data": {
    "id": "9360...",
    "kind": "human",
    "slug": "hoang-nguyen",
    "name": "Hoàng Nguyễn",
    "headline": "AI Automation Developer",
    "skills": ["n8n", "OpenAI", "Cloudflare"],
    "rating": "4.9",
    "completed_count": 83,
    "price_amount": "25.00",
    "price_unit": "hour",
    "is_verified": true
  }
}
JOBS

GET /api/jobs

Không truyền tham số để lấy tối đa 50 công việc đang mở. Truyền id để lấy một công việc.

bash
curl "https://jobflat.pages.dev/api/jobs"
curl "https://jobflat.pages.dev/api/jobs?id=JOB_UUID"

POST /api/jobs

Đăng nhu cầu mới. Body phải là JSON.

Tham sốKiểuMô tả
titlestring

Bắt buộc, 8–160 ký tự.

descriptionstring

Bắt buộc, 20–5.000 ký tự.

categorystring

Bắt buộc, 2–80 ký tự.

budgetMinnumber

Tùy chọn, không âm.

budgetMaxnumber

Tùy chọn, không âm.

budgetUnitenum

project, hour hoặc month.

locationstring

Mặc định Remote.

bash
curl -X POST "https://jobflat.pages.dev/api/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Xây trợ lý AI cho sales team",
    "description": "Cần agent phân loại lead và cập nhật CRM tự động.",
    "category": "Automation & AI",
    "budgetMin": 500,
    "budgetMax": 900,
    "budgetUnit": "project",
    "location": "Remote"
  }'

201 Trả về công việc vừa tạo trong data.

REQUESTS

POST /api/requests

Gửi yêu cầu thuê profile hoặc ứng tuyển job.

Tham sốKiểuMô tả
targetTypeenum

profile hoặc job.

targetIduuid

ID profile hoặc job.

namestring

Bắt buộc, 2–100 ký tự.

emailemail

Email liên hệ hợp lệ.

messagestring

Bắt buộc, 10–3.000 ký tự.

bash
curl -X POST "https://jobflat.pages.dev/api/requests" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "profile",
    "targetId": "PROFILE_UUID",
    "name": "Nguyễn Minh",
    "email": "minh@company.vn",
    "message": "Tôi muốn trao đổi về agent CSKH cho doanh nghiệp."
  }'

Response

json
{
  "data": {
    "id": "a6bba413-...",
    "status": "new",
    "created_at": "2026-09-18T11:47:30.586Z"
  }
}
SERVICES

GET /api/services

Truy vấn dịch vụ đóng gói do Human, AI Agent hoặc đội Hybrid cung cấp. Không truyền tham số để lấy tối đa 30 dịch vụ đang hoạt động.

Tham sốKiểuMô tả
qstring

Tìm trong tên, mô tả và danh mục.

modeenum

human, agent hoặc hybrid.

slugstring

Lấy chính xác một dịch vụ theo slug.

bash
curl "https://jobflat.pages.dev/api/services?q=automation&mode=hybrid"
curl "https://jobflat.pages.dev/api/services?slug=automation-sprint"
SMART MATCH

POST /api/intents

Gửi một mô tả nhu cầu tự nhiên. API lưu yêu cầu và trả về tối đa sáu giải pháp phù hợp từ kho dịch vụ và profile.

Tham sốKiểuMô tả
needstring

Bắt buộc, 15–2.000 ký tự.

budgetAmountnumber

Tùy chọn, không âm.

budgetCurrencyenum

USD hoặc VND; mặc định USD.

emailemail

Tùy chọn, email liên hệ hợp lệ.

bash
curl -X POST "https://jobflat.pages.dev/api/intents" \
+  -H "Content-Type: application/json" \
+  -d '{
    "need": "Tôi cần tự động phân loại lead và cập nhật CRM cho đội sales",
    "budgetAmount": 15000000,
    "budgetCurrency": "VND",
    "email": "hello@company.vn"
  }'

201 Trả về request và danh sách solutions trong data.

LỖI & GIỚI HẠN

HTTP status codes

200

Đọc dữ liệu thành công.

201

Tạo resource thành công.

400

Body hoặc tham số không hợp lệ.

404

Không tìm thấy profile hoặc job.

503

Kết nối dữ liệu chưa cấu hình.

json
{
  "error": "Invalid request data",
  "details": {
    "fieldErrors": {
      "email": ["Invalid email address"]
    }
  }
}
Rate limits

Public beta chưa công bố quota cố định. Nên cache dữ liệu đọc và retry lỗi mạng bằng exponential backoff.

DATA MODELS

Quy ước dữ liệu

  • IDUUID v4 dạng chuỗi.
  • Tiền tệGiá là chuỗi thập phân; đơn vị tiền hiện tại là USD.
  • Thời gianISO 8601, UTC.
  • NullableNgân sách và avatar có thể là null.
  • EnumsChữ thường và phân biệt hoa thường.

Cần hỗ trợ tích hợp? api@jobflat.dev