Lire, créer et retirer des offres par API

Lire les offres actives

GET /v2/jobs exige jobs:read, read ou une permission accordant cette lecture.

Paramètre	Signification
`q`	Recherche dans le titre, l’entreprise et les tags.
`job_type`	`fulltime`, `parttime`, `freelance` ou `internship`.
`remote`	Télétravail : `true` ou `false`.
`city`	Identifiant URL de ville, par exemple `berlin`.
`page`, `per_page`	Pagination si activée côté serveur ; maximum 50 par page.

curl --fail-with-body --max-time 30   'https://api.coworkies.com/v2/jobs?city=berlin&job_type=fulltime'   -H "X-API-Key: ${COWORKIES_API_KEY}"

Une clé d’espace retourne les offres de cet espace dans data.jobs. Si data.pagination existe, utilisez has_next et current_page. Sinon, le serveur retourne la liste complète avec data.total : ne supposez pas que per_page limite la réponse.

Créer une offre

POST /v2/jobs exige jobs:write ou write. Envoyez du JSON.

Champ obligatoire	Valeur
`title`	Titre de l’offre.
`company`	Nom de l’entreprise.
`description`	Texte ou HTML simple (`p`, `br`, `ul`, `ol`, `li`, `h2`, `h3`, `strong`, `em`, `a`).
`job_type`	`fulltime`, `parttime`, `freelance` ou `internship`.
`tags`	Tags séparés par des virgules.
`id_city` ou `city_name`	Identifiant de ville confirmée ou nom résolvable.

Les champs facultatifs comprennent external_url, apply_url, is_remote (0 ou 1), inv_email, currency (EUR, USD, GBP), sal_min, sal_max, id_space et id_plan (valeur par défaut 5). Le salaire minimum ne peut pas dépasser le maximum. Consultez la référence complète pour tous les champs.

L’espace de la clé est affecté automatiquement ; un id_space contradictoire est rejeté. Les tags sont nettoyés, mis en minuscules et dédupliqués. Le nom de ville est résolu par correspondance exacte puis par préfixe. Utilisez id_city pour un nom ambigu. L’URL source reçoit un paramètre de référencement Coworkies.

# Valeur unique pour une nouvelle offre ; conserver pour ses nouvelles tentatives.
COWORKIES_JOB_REQUEST_ID='space-job-community-manager-001'
curl --fail-with-body --max-time 30   'https://api.coworkies.com/v2/jobs'   -X POST   -H "X-API-Key: ${COWORKIES_API_KEY}"   -H 'Content-Type: application/json'   -H "Idempotency-Key: ${COWORKIES_JOB_REQUEST_ID}"   -d '{
    "title": "Community Manager",
    "company": "Example Workspace",
    "description": "Lead member experience at our Berlin workspace.",
    "job_type": "fulltime",
    "city_name": "Berlin",
    "tags": "community,events,hospitality",
    "apply_url": "https://example.com/careers/apply",
    "is_remote": 0,
    "currency": "EUR",
    "sal_min": 35000,
    "sal_max": 45000
  }'

Vérifier la publication

Pour un espace Pro confirmé, une nouvelle offre API peut être publiée automatiquement en active. Les autres offres créées par une clé d’espace commencent en draft. Les importateurs de plateforme autorisés peuvent aussi publier automatiquement. Un champ status fourni par le client ne force pas l’état initial.

Vérifiez data.status, data.action, data.job_id et les liens de consultation, de modification ou de paiement retournés. Une réponse réussie ne garantit pas une visibilité publique. Suivez le lien retourné si une action supplémentaire est nécessaire.

Doublons et nouvelles tentatives

L’API compare le titre, l’entreprise, la ville et l’URL source normalisés. Une correspondance met à jour l’offre existante ; data.action vaut created ou updated. Une offre expirée ou suspendue n’est pas automatiquement réactivée par cette mise à jour.

Idempotency-Key (200 caractères maximum) évite de répéter une création réussie lors d’un nouvel envoi identique. Réutilisez-le pour cette requête seulement. Traitez 409 et 429 selon le guide des erreurs.

Retirer une offre

POST /v2/jobs/unpublish exige une permission d’écriture et une offre appartenant à l’espace de la clé.

curl --fail-with-body --max-time 30   'https://api.coworkies.com/v2/jobs/unpublish'   -X POST   -H "X-API-Key: ${COWORKIES_API_KEY}"   -H 'Content-Type: application/json'   -d '{"job_id": 1234}'

Remplacez 1234 par data.job_id. Le retrait retourne un état expiré et unpublished. Une offre déjà expirée ou fermée retourne already_unpublished. La fiche est retirée des résultats actifs sans être supprimée.