콘텐츠로 이동
Schift Docs

작업(Jobs)

Show:

**job(작업)**은 document(문서)를 수집(ingest)하고 embedding(임베딩)하거나 API task(작업)를 실행하는 등의 비동기 작업 단위다. /v1/jobs 엔드포인트(endpoint)로 organization(조직) 내 작업을 조회하고, 제어하고, 정리한다.

참고: 모든 /v1/jobs 엔드포인트는 Authorization: Bearer <token> 헤더에 workspace API key(워크스페이스 API 키)가 필요한다. 읽기 작업은 유효한 키를 허용하며, 쓰기 작업(cancel, reprocess, delete)은 jobs:write scope(권한 범위)가 필요한다.

Job 객체(작업)

섹션 제목: “Job 객체(작업)”
필드타입설명
idstring고유한 작업 식별자이다.
org_idstring작업을 소유한 organization(조직)이다.
bucket_idstring작업이 속한 bucket(버킷)이다.
collection_idstring | null작업 대상 collection(컬렉션). (해당하는 경우)
document_idstring | null연결된 수집 document(문서). (해당하는 경우)
workflow_idstring | null연결된 workflow(워크플로우). (해당하는 경우)
source_entry_idstring | null연결된 source entry(소스 항목). (해당하는 경우)
priorityintegerpriority(우선순위) 값이 낮을수록 먼저 실행된다(기본값 2).
statusstringqueued, extracting, chunking, embedding, indexing, ready, failed, cancelled 중 하나이다.
s3_keystring원본 파일 또는 artifact(아티팩트)의 저장소 키이다.
file_namestring원본 파일 이름이다.
file_sizeinteger파일 크기(바이트)이다.
file_typestring | null파일 타입이다. 예: pdf, txt, embed_bulk.
processing_typestring | nullsource_connector, bucket_page_reindex 또는 다른 task type(작업 유형)이다.
estimated_costnumber큐에 넣을 때 예상 비용이다.
actual_costnumber | null완료 후 실제 비용이다.
chunks_countinteger | null생성된 chunk(청크) 개수이다. (해당하는 경우)
failed_phasestring | null상태가 failed일 때 실패한 phase(단계)이다.
error_categorystring | null분류된 오류 원인이다.
error_messagestring | null사람이 읽을 수 있는 오류 메시지이다.
retryableboolean | null실패가 재시도 가능한지 여부이다.
retry_countinteger재시도 횟수이다.
reprocess_of_job_idstring | null이 작업이 재처리(reprocess) 재시도인 경우 원본 작업 ID이다.
worker_idstring | null현재 작업을 처리 중인 worker(워커)이다.
scheduled_atstring | null지연된 경우 ISO 8601 예약 시간이다.
started_atstring | nullISO 8601 처리 시작 시간이다.
completed_atstring | nullISO 8601 완료 시간이다.
created_atstringISO 8601 생성 시간이다.
updated_atstringISO 8601 마지막 업데이트 시간이다.
metadata_snapshotobject | nullaudit(감사) 안전을 위해 원본 document(문서) metadata(메타데이터)의 스냅샷이다.

GET /v1/jobs/{job_id}

섹션 제목: “GET /v1/jobs/{job_id}”

ID로 단일 작업을 조회한다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
job_idstringYesJob(작업) 식별자이다.

응답 예시

섹션 제목: “응답 예시”
{
  "id": "job_01J8X...",
  "org_id": "org_abc123",
  "bucket_id": "bucket_legal",
  "collection_id": null,
  "document_id": "doc_01J8X...",
  "priority": 1,
  "status": "ready",
  "s3_key": "org_abc123/uploads/contract.pdf",
  "file_name": "contract.pdf",
  "file_size": 1048576,
  "file_type": "pdf",
  "estimated_cost": 0.05,
  "actual_cost": 0.047,
  "chunks_count": 42,
  "failed_phase": null,
  "error_category": null,
  "error_message": null,
  "retryable": null,
  "retry_count": 0,
  "reprocess_of_job_id": null,
  "worker_id": null,
  "scheduled_at": null,
  "started_at": "2026-06-19T04:12:00Z",
  "completed_at": "2026-06-19T04:12:08Z",
  "created_at": "2026-06-19T04:11:55Z",
  "updated_at": "2026-06-19T04:12:08Z",
  "metadata_snapshot": {
    "file_name": "contract.pdf",
    "source_path": "org_abc123/uploads/contract.pdf",
    "captured_at": "2026-06-19T04:11:55Z"
  }
}

오류

섹션 제목: “오류”
상태원인
404작업을 찾을 수 없거나 해당 organization(조직)에 속하지 않는다.

GET /v1/jobs

섹션 제목: “GET /v1/jobs”

organization(조직)의 작업을 최신순으로 조회한다.

쿼리 매개변수

섹션 제목: “쿼리 매개변수”
매개변수타입필수기본값설명
bucket_idstringNo,특정 bucket(버킷)으로 필터링한다.
statusstringNo,특정 status(상태)로 필터링한다.
limitintegerNo50최대 결과 수이다. 1~200 사이여야 한다.

응답 예시

섹션 제목: “응답 예시”
[
  {
    "id": "job_01J8X...",
    "org_id": "org_abc123",
    "bucket_id": "bucket_legal",
    "status": "ready",
    "file_name": "contract.pdf",
    "file_size": 1048576,
    "file_type": "pdf",
    "priority": 1,
    "created_at": "2026-06-19T04:11:55Z",
    "updated_at": "2026-06-19T04:12:08Z"
  },
  {
    "id": "job_01J8Y...",
    "org_id": "org_abc123",
    "bucket_id": "bucket_hr",
    "status": "failed",
    "file_name": "handbook.docx",
    "file_size": 512000,
    "file_type": "docx",
    "priority": 2,
    "error_message": "Provider embedding timeout",
    "created_at": "2026-06-19T03:00:00Z",
    "updated_at": "2026-06-19T03:05:00Z"
  }
]

GET /v1/jobs/{job_id}/files

섹션 제목: “GET /v1/jobs/{job_id}/files”

job(작업)과 연결된 파일을 조회한다. Schift의 작업은 현재 단일 document(문서) 단위이므로 최대 하나의 파일을 반환한다. 응답 형식은 OpenAI의 vector_store.file 객체와 동일한다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
job_idstringYesJob(작업) 식별자이다.

응답 예시

섹션 제목: “응답 예시”
{
  "object": "list",
  "data": [
    {
      "id": "doc_01J8X...",
      "object": "vector_store.file",
      "vector_store_id": "bucket_legal",
      "status": "uploaded",
      "filename": "contract.pdf",
      "created_at": "2026-06-19T04:11:55Z"
    }
  ],
  "has_more": false
}

오류

섹션 제목: “오류”
상태원인
404작업을 찾을 수 없거나 해당 organization(조직)에 속하지 않는다.

GET /v1/jobs/{job_id}/download

섹션 제목: “GET /v1/jobs/{job_id}/download”

job(작업)과 연결된 원본 파일을 다운로드한다. 응답은 attachment(첨부) Content-Disposition 헤더와 함께 binary stream(바이너리 스트림)으로 반환된다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
job_idstringYesJob(작업) 식별자이다.

응답

섹션 제목: “응답”

바이너리 파일 콘텐츠이다. Content-Type은 작업의 file_type에서 가져오며, 기본값은 application/octet-stream이다.

오류

섹션 제목: “오류”
상태원인
404작업을 찾을 수 없거나, 작업에 파일이 없거나, 저장소에서 파일을 가져올 수 없는다.

POST /v1/jobs/{job_id}/cancel

섹션 제목: “POST /v1/jobs/{job_id}/cancel”

queued(대기) 상태 또는 진행 중인 작업을 취소한다.

참고: 이 엔드포인트는 jobs:write scope(권한 범위)가 필요한다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
job_idstringYesJob(작업) 식별자이다.

쿼리 매개변수

섹션 제목: “쿼리 매개변수”
매개변수타입필수기본값설명
forcebooleanNofalse작업이 진행 중이어도 강제로 취소(force-cancel)할지 여부이다.

동작

섹션 제목: “동작”
  • 작업이 이미 terminal state(종료 상태)(ready, failed, cancelled)에 있으면, 응답은 현재 상태와 함께 detail: "job already in terminal state"를 반환한다.
  • 작업이 진행 중이고 force가 false이면, 엔드포인트는 400을 반환하고 ?force=true 사용을 권장한다.
  • force=true이면 작업은 현재 진행 상태와 관계없이 cancelled로 표시된다.

응답 예시

섹션 제목: “응답 예시”
{
  "status": "cancelled"
}

오류 예시

섹션 제목: “오류 예시”
상태원인
400진행 중인 작업이면서 force=false인 경우이다.
404작업을 찾을 수 없거나 해당 organization(조직)에 속하지 않는다.
409작업이 더 이상 queued(대기) 상태가 아닙다(경쟁 상태).

POST /v1/jobs/{job_id}/reprocess

섹션 제목: “POST /v1/jobs/{job_id}/reprocess”

실패했거나 다른 이유로 terminal state(종료 상태)인 작업을 다시 처리하는 새로운 작업을 생성한다. 새 작업은 원본 source(소스), bucket(버킷), collection(컬렉션), priority(우선순위)를 복사하고 reprocess_of_job_id를 통해 원본과 연결된다.

참고: 이 엔드포인트는 jobs:write scope(권한 범위)가 필요한다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
job_idstringYesJob(작업) 식별자이다.

응답 예시

섹션 제목: “응답 예시”
{
  "id": "job_01J8Z...",
  "org_id": "org_abc123",
  "bucket_id": "bucket_legal",
  "document_id": "doc_01J8X...",
  "status": "queued",
  "file_name": "contract.pdf",
  "file_size": 1048576,
  "priority": 1,
  "reprocess_of_job_id": "job_01J8X...",
  "created_at": "2026-06-19T05:00:00Z",
  "updated_at": "2026-06-19T05:00:00Z"
}

오류

섹션 제목: “오류”
상태원인
400작업이 terminal state(종료 상태)가 아닙다.
404작업을 찾을 수 없거나 해당 organization(조직)에 속하지 않는다.

DELETE /v1/jobs/{job_id}

섹션 제목: “DELETE /v1/jobs/{job_id}”

작업을 삭제한다. 진행 중인 작업은 삭제할 수 없는다.

참고: 이 엔드포인트는 jobs:write scope(권한 범위)가 필요한다.

경로 매개변수

섹션 제목: “경로 매개변수”
매개변수타입필수설명
job_idstringYesJob(작업) 식별자이다.

응답

섹션 제목: “응답”

성공 시 204 No Content를 반환한다.

오류

섹션 제목: “오류”
상태원인
400진행 중인 작업은 삭제할 수 없는다.
404작업을 찾을 수 없거나 해당 organization(조직)에 속하지 않는다.

POST /v1/admin/reap-stale-jobs

섹션 제목: “POST /v1/admin/reap-stale-jobs”

오래 멈춰 있는 진행 중인 job(작업)을 failed로 표시한다. 이 엔드포인트는 cron이나 platform administrator(플랫폼 관리자)가 죽은 worker(워커)로부터 복구하기 위해 사용된다.

참고: 이 엔드포인트는 일반적인 workspace API key(워크스페이스 API 키)를 사용하지 않는다. 다음 중 하나를 허용한다:

  • Authorization: Bearer <token> 헤더에 포함된 platform_admin JWT 또는 API key(API 키).
  • 서버의 CRON_SECRET 환경 변수와 일치하는 X-Cron-Secret 헤더.

쿼리 매개변수

섹션 제목: “쿼리 매개변수”
매개변수타입필수기본값설명
timeout_minutesintegerNo30작업이 얼마나 오래 멈춰 있어야 reap(정리)되는지(분). 범위는 1–1440이다.

요청 헤더

섹션 제목: “요청 헤더”
헤더필수설명
X-Cron-SecretConditionalCloud Scheduler / CLI 호출자를 위한 cron secret(크론 시크릿)이다.
AuthorizationConditionalUI 또는 수동 사용을 위한 Bearer <platform_admin_token>이다.

응답 예시

섹션 제목: “응답 예시”
{
  "timeout_minutes": 30,
  "reaped_count": 2,
  "jobs": [
    {
      "job_id": "job_01J8X...",
      "org_id": "org_abc123",
      "stuck_status": "embedding"
    },
    {
      "job_id": "job_01J8Y...",
      "org_id": "org_def456",
      "stuck_status": "extracting"
    }
  ]
}

오류

섹션 제목: “오류”
상태원인
401유효한 인증이 제공되지 않았는다.
403X-Cron-Secret 헤더가 있지만 유효하지 않는다.

관련 문서

섹션 제목: “관련 문서”