`, `
`) or at least explicit line breaks
(`\n`). The JD is stored and rendered as-is — in the generated JD PDF
and as interview context — so a single flattened plain-text line loses
all headings, bullets, and line breaks. Descriptions shorter than 700
characters are rejected with a validation error: send the real job
description, not a stub.
**The description must state a workplace type and a location.**
Workplace type (e.g. On-site, Remote, Hybrid) and location (a city or
country) are extracted from the description text — they are not request
fields. If either is missing from the text, the request is rejected with
a `422` whose `errors` message names exactly what to add; nothing is
created or charged.
The job is created with a **default AI interviewer** (type
`QUICK_BEHAVIORAL`, language `EN`) that is **seeded with prescreening
questions generated from your job description** — must-have skills are
extracted from the JD and a question set is generated for them — so the
job is immediately interviewable. Interviews created from the job (`POST
/interviews`) carry those questions. Question generation is best-effort:
if it fails, the job is still created and the interview runs on the job
description plus a resume question. Override the language with the
optional `language` field.
**Production side effects:** on the production server this runs the full
job pipeline — it publishes the job to your connected job board
(Workable / ATS) and consumes credits. Use the staging server
(`https://interview.gomu.ai/api/v1`) to build and verify your
integration first, without publishing or being charged. This endpoint is
**not idempotent** — calling it twice creates two jobs.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobRequest'
example:
title: Backend Engineer
description: >-
About the role
We are hiring a Backend Engineer with
strong TypeScript and Postgres experience to build and scale our
API platform, working closely with product and data teams to
ship reliable, well-tested services.
Workplace:
Hybrid — Ho Chi Minh City,
Vietnam
Responsibilities
- Design, build, and
operate high-throughput REST services in Node.js and
TypeScript
- Own PostgreSQL schema design, query
performance, and data integrity
- Set up observability,
alerting, and CI/CD for the services you own
- Review code
and mentor junior
engineers
Requirements
- 5+ years of
backend experience in production environments
- Strong SQL
and data-modeling skills
- Experience with distributed
systems, message queues, and caching
- Clear written and
spoken English
responses:
'200':
description: >-
Job created. Returns the new job id, usable immediately as
`qodeJobId` on `POST /interviews`.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobResponse'
example:
success: true
data:
qodeJobId: 826ae7c5-1f2a-4c3d-9b8e-2a1c4d5e6f70
name: Backend Engineer
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ValidationError'
'422':
description: >-
The job description text is missing required information (workplace
type and/or location). The `errors` message names exactly what to
add. Nothing is created or charged.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 422
errors: >-
The job description is missing required information: workplace
type (e.g. "On-site", "Remote", "Hybrid"); location (a city or
country). Add the missing details to the description and try
again.
'500':
$ref: '#/components/responses/ServerError'
security:
- ApiKeyAuth: []
components:
schemas:
CreateJobRequest:
type: object
required:
- title
- description
properties:
title:
type: string
minLength: 1
maxLength: 80
description: Job title. Becomes the job name and the created interview's name.
description:
type: string
minLength: 700
maxLength: 20000
description: >-
The job description (JD), minimum 700 characters. Send it as rich
text — HTML markup (``, `
`, `- `, `
`) or at least
explicit line breaks (`\n`) — not a single flattened plain-text
line: the JD is stored and rendered as-is (JD PDF, interview
context), so unformatted text loses headings, bullets, and line
breaks. It must state a workplace type (e.g. On-site, Remote,
Hybrid) and a location (a city or country) — both are extracted from
the text, and a description missing either is rejected with a 422
naming what to add.
language:
type: string
enum:
- DE
- EN
- EN_IN
- ES
- FR
- ID
- JA
- KO
- NL
- VI
default: EN
description: >-
Optional. Interview language for the auto-created AI interviewer.
Defaults to EN.
CreateJobResponse:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
qodeJobId:
type: string
description: >-
The created job's id. Pass it to `POST /interviews` as
`qodeJobId`.
name:
type: string
description: The job name (the title you supplied).
Error:
type: object
properties:
status:
type: integer
example: 401
errors:
oneOf:
- type: string
- type: array
items:
type: object
description: Either a human-readable string or a list of Zod validation issues.
responses:
Unauthorized:
description: API key missing, malformed, expired, or revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 401
errors: Invalid API key
ValidationError:
description: >-
Request body failed Zod validation. The `errors` field contains the
issue list.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServerError:
description: Unexpected server-side failure. Safe to retry with exponential backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: Opaque token (starts with `qint_`)
description: >-
Provide the API key issued to you by your organization admin. Send it as
`Authorization: Bearer ` on every request.
````