API Reference

GrydJobs exposes three REST API controllers for managing jobs, recurring schedules, and the dead letter queue.

All endpoints require authentication ([Authorize]) and return RFC 7807 ProblemDetails on errors.

Jobs

Base path: GET /api/v1/jobs

List Jobs

GET /api/v1/jobs?page=1&pageSize=20&status=Processing&queue=default&orderBy=CreatedAt&ascending=false

Query Parameters:

Parameter	Type	Default	Description
page	int	1	Page number
pageSize	int	20	Page size
status	enum	—	Filter by status (Enqueued, Processing, Succeeded, Failed, etc.)
type	enum	—	Filter by type (FireAndForget, Delayed, Recurring, Continuation)
priority	enum	—	Filter by priority (Low, Normal, High, Critical)
queue	string	—	Filter by queue name
searchTerm	string	—	Search in job type name
orderBy	string	CreatedAt	Sort field
ascending	bool	false	Sort direction

Response: 200 OK — PagedResult<JobSummaryDto>

Get Job by ID

GET /api/v1/jobs/{id}

Response: 200 OK — JobSummaryDto | 404 Not Found

Get Execution History

GET /api/v1/jobs/{id}/executions?page=1&pageSize=20

Response: 200 OK — PagedResult<JobExecutionDto> | 404 Not Found

Get Dashboard Stats

GET /api/v1/jobs/dashboard/stats

Response: 200 OK — JobDashboardStatsDto

{
  "totalJobs": 1523,
  "enqueuedJobs": 12,
  "processingJobs": 4,
  "succeededJobs": 1480,
  "failedJobs": 15,
  "deadLetteredJobs": 3,
  "scheduledJobs": 8,
  "recurringJobs": 5,
  "averageExecutionDurationMs": 342.5,
  "totalExecutions": 4210
}

Enqueue Job

POST /api/v1/jobs
Content-Type: application/json

{
  "jobTypeName": "MyApp.Jobs.SendEmailJob, MyApp",
  "serializedArgs": "{\"to\":\"user@example.com\"}",
  "argsTypeName": "MyApp.Jobs.SendEmailArgs, MyApp",
  "priority": "Normal",
  "queue": "default",
  "scheduledAt": null,
  "maxRetries": 3
}

Response: 201 Created — JobSummaryDto | 400 Bad Request

Cancel Job

POST /api/v1/jobs/{id}/cancel

Response: 200 OK | 404 Not Found | 400 Bad Request

Error codes: JOB_NOT_FOUND, JOB_ALREADY_CANCELLED, JOB_CANNOT_CANCEL

---

Recurring Jobs

Base path: /api/v1/recurring-jobs

List Recurring Jobs

GET /api/v1/recurring-jobs?page=1&pageSize=20

Response: 200 OK — PagedResult<RecurringJobDto>

Get Recurring Job

GET /api/v1/recurring-jobs/{id}

Response: 200 OK — RecurringJobDto | 404 Not Found

Create Recurring Job

POST /api/v1/recurring-jobs
Content-Type: application/json

{
  "jobId": "daily-cleanup",
  "jobTypeName": "MyApp.Jobs.CleanupJob, MyApp",
  "cronExpression": "0 2 * * *",
  "timeZoneId": "America/Sao_Paulo",
  "queue": "low"
}

Response: 201 Created — RecurringJobDto | 409 Conflict

Update Recurring Job

PUT /api/v1/recurring-jobs/{id}
Content-Type: application/json

{
  "cronExpression": "0 3 * * *",
  "timeZoneId": "UTC",
  "queue": "default"
}

Response: 200 OK — RecurringJobDto | 404 Not Found

Delete Recurring Job

DELETE /api/v1/recurring-jobs/{id}

Response: 204 No Content | 404 Not Found

Pause Recurring Job

POST /api/v1/recurring-jobs/{id}/pause

Response: 200 OK | 404 Not Found | 400 Bad Request

Resume Recurring Job

POST /api/v1/recurring-jobs/{id}/resume

Response: 200 OK | 404 Not Found | 400 Bad Request

Trigger Recurring Job

POST /api/v1/recurring-jobs/{id}/trigger

Immediately executes the job outside its normal schedule.

Response: 200 OK | 404 Not Found

---

Dead Letter Queue

Base path: /api/v1/dead-letter-jobs

List Dead Letter Jobs

GET /api/v1/dead-letter-jobs?page=1&pageSize=20

Response: 200 OK — PagedResult<DeadLetterJobDto>

Retry Dead Letter Job

POST /api/v1/dead-letter-jobs/{id}/retry

Re-enqueues the failed job for another attempt.

Response: 200 OK | 404 Not Found | 400 Bad Request

Error codes: JOB_DEADLETTER_NOT_FOUND, JOB_DEADLETTER_ALREADY_RETRIED

Purge Dead Letter Queue

POST /api/v1/dead-letter-jobs/purge
Content-Type: application/json

{ "retentionDays": 30 }

If retentionDays is null or body is empty, purges all entries.

Response: 200 OK | 400 Bad Request

---

Error Codes

All error codes follow the JOB_{ENTITY}_{SUFFIX} convention:

Error Code	HTTP Status	Description
JOB_NOT_FOUND	404	Job not found
JOB_ALREADY_CANCELLED	400	Job is already cancelled
JOB_CANNOT_CANCEL	400	Job cannot be cancelled (completed/processing)
JOB_RECURRING_NOT_FOUND	404	Recurring job not found
JOB_RECURRING_ALREADY_EXISTS	409	Recurring job ID already taken
JOB_RECURRING_ALREADY_PAUSED	400	Already paused
JOB_RECURRING_NOT_PAUSED	400	Not paused
JOB_DEADLETTER_NOT_FOUND	404	Dead letter entry not found
JOB_DEADLETTER_ALREADY_RETRIED	400	Already retried