{"openapi":"3.1.0","info":{"title":"Emerald Field OS API","version":"1.0.0","description":"Read crew time, pay lines, jobs, dailies and production, and subscribe to webhooks. Available on the Pro plan.\n\nAuthenticate with `Authorization: Bearer <apiKey>` (create keys in Settings → API & webhooks). Money is integer cents; durations are integer minutes; calendar dates are `YYYY-MM-DD`. List endpoints use cursor pagination (`limit`, `cursor` → `nextCursor`). Rate limit: 600 requests per minute per key (`X-RateLimit-*` headers). Errors always look like `{ \"error\": { \"code\", \"message\" } }`."},"servers":[{"url":"https://emeraldfieldos.com/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"People"},{"name":"Jobs"},{"name":"Time"},{"name":"Payroll"},{"name":"Dailies"},{"name":"Production"},{"name":"Webhooks"}],"paths":{"/employees":{"get":{"operationId":"getEmployees","summary":"List employees","tags":["People"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"description":"Page size (1–200, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ACTIVE","INACTIVE","TERMINATED","PENDING_SETUP"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"operationId":"getProjects","summary":"List projects (jobs)","tags":["Jobs"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"description":"Page size (1–200, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["BIDDING","ACTIVE","ON_HOLD","COMPLETED"]},"description":"Project status"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cost-codes":{"get":{"operationId":"getCostCodes","summary":"List cost codes","tags":["Jobs"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"description":"Page size (1–200, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page"},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CostCode"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shifts":{"get":{"operationId":"getShifts","summary":"List shifts with cost-code allocations","tags":["Time"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"description":"Page size (1–200, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page"},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"First work date (inclusive)"},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Last work date (inclusive)"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["OPEN","SUBMITTED","SUPERVISOR_APPROVED","PAYROLL_APPROVED","EXPORTED","LOCKED"]}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Shift"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pay-lines":{"get":{"operationId":"getPayLines","summary":"List computed pay lines","description":"Rate-engine output per shift allocation. Amounts are integer cents; minutes are integers.","tags":["Payroll"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"description":"Page size (1–200, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page"},{"name":"periodId","in":"query","required":false,"schema":{"type":"string"},"description":"Pay period id; omit for all periods"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PayLine"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/dailies":{"get":{"operationId":"getDailies","summary":"List daily reports","tags":["Dailies"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"description":"Page size (1–200, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page"},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Calendar date, YYYY-MM-DD"},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Calendar date, YYYY-MM-DD"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["DRAFT","SUBMITTED","SIGNED","SENT"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DailyReport"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/production":{"get":{"operationId":"getProduction","summary":"List production entries","tags":["Production"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200},"description":"Page size (1–200, default 50)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"`nextCursor` from the previous page"},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Calendar date, YYYY-MM-DD"},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Calendar date, YYYY-MM-DD"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductionEntry"}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"post":{"operationId":"postWebhooks","summary":"Subscribe a webhook endpoint","description":"Deliveries are POSTed as JSON and signed with `X-EmeraldField-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"t.body\">`.","tags":["Webhooks"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["*","shift.approved","period.synced","daily.submitted","form.flagged","incident.created"]},"description":"Event names, or [\"*\"] for all"}},"required":["url","events"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API (Pro required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters (Zod issues in `error.details`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (600 requests / minute / key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"event":{"post":{"summary":"Outbound event delivery","description":"Events: shift.approved, period.synced, daily.submitted, form.flagged, incident.created. Verify `X-EmeraldField-Signature` before trusting the body. Non-2xx responses are retried up to 5 times with exponential backoff.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"createdAt":{"type":"string"},"companyId":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Acknowledge receipt with any 2xx"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code, e.g. UNAUTHENTICATED, RATE_LIMITED"},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Employee":{"type":"object","properties":{"id":{"type":"string"},"employeeNumber":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"preferredName":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"language":{"type":"string","enum":["EN","ES"]},"status":{"type":"string","enum":["ACTIVE","INACTIVE","TERMINATED","PENDING_SETUP"]},"hireDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date, YYYY-MM-DD"},{"type":"null"}]},"defaultClassificationId":{"type":["string","null"]},"externalIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"updatedAt":{"type":"string","description":"ISO 8601 timestamp (UTC)"}},"required":["id","employeeNumber","firstName","lastName","preferredName","phone","email","language","status","hireDate","defaultClassificationId","externalIds","updatedAt"],"additionalProperties":false},"Project":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"name":{"type":"string"},"customerName":{"type":["string","null"]},"status":{"type":"string"},"timezone":{"type":"string"},"startDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date, YYYY-MM-DD"},{"type":"null"}]},"endDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date, YYYY-MM-DD"},{"type":"null"}]},"isPrevailingWage":{"type":"boolean"},"isUnion":{"type":"boolean"},"externalIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"updatedAt":{"type":"string","description":"ISO 8601 timestamp (UTC)"}},"required":["id","number","name","customerName","status","timezone","startDate","endDate","isPrevailingWage","isUnion","externalIds","updatedAt"],"additionalProperties":false},"CostCode":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"costType":{"type":"string","enum":["LABOR","EQUIPMENT","MATERIAL","SUB","OTHER"]},"unit":{"type":["string","null"]},"budgetQty":{"type":["number","null"]},"budgetMinutes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"isActive":{"type":"boolean"},"isTM":{"type":"boolean"},"updatedAt":{"type":"string","description":"ISO 8601 timestamp (UTC)"}},"required":["id","projectId","code","description","costType","unit","budgetQty","budgetMinutes","isActive","isTM","updatedAt"],"additionalProperties":false},"Shift":{"type":"object","properties":{"id":{"type":"string"},"employeeId":{"type":"string"},"projectId":{"type":"string"},"workDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date, YYYY-MM-DD"},"classificationId":{"type":"string"},"crewId":{"type":["string","null"]},"status":{"type":"string"},"entryMethod":{"type":"string"},"totalMinutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"breakMinutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"injuryAttestation":{"type":["string","null"]},"payPeriodId":{"type":["string","null"]},"flags":{"type":"array","items":{"type":"string"}},"allocations":{"type":"array","items":{"type":"object","properties":{"costCodeId":{"type":"string"},"minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"equipmentId":{"type":["string","null"]}},"required":["costCodeId","minutes","equipmentId"],"additionalProperties":false}},"updatedAt":{"type":"string","description":"ISO 8601 timestamp (UTC)"}},"required":["id","employeeId","projectId","workDate","classificationId","crewId","status","entryMethod","totalMinutes","breakMinutes","injuryAttestation","payPeriodId","flags","allocations","updatedAt"],"additionalProperties":false},"PayLine":{"type":"object","properties":{"id":{"type":"string"},"shiftId":{"type":"string"},"employeeId":{"type":"string"},"workDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date, YYYY-MM-DD"},"payType":{"type":"string"},"minutes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rateCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fringeCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"costCodeId":{"type":"string"},"classificationId":{"type":"string"},"isPrevailing":{"type":"boolean"}},"required":["id","shiftId","employeeId","workDate","payType","minutes","rateCents","fringeCents","amountCents","costCodeId","classificationId","isPrevailing"],"additionalProperties":false},"DailyReport":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"reportDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date, YYYY-MM-DD"},"status":{"type":"string"},"workPerformed":{"type":["string","null"]},"safetyNotes":{"type":["string","null"]},"delays":{"anyOf":[{},{"type":"null"}]},"weather":{"anyOf":[{},{"type":"null"}]},"manpower":{"anyOf":[{},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp (UTC)"},{"type":"null"}]},"pdfUrl":{"type":["string","null"]},"updatedAt":{"type":"string","description":"ISO 8601 timestamp (UTC)"}},"required":["id","projectId","reportDate","status","workPerformed","safetyNotes","delays","weather","manpower","signedAt","pdfUrl","updatedAt"],"additionalProperties":false},"ProductionEntry":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"costCodeId":{"type":"string"},"workDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date, YYYY-MM-DD"},"qty":{"type":"number"},"unit":{"type":"string"},"location":{"type":["string","null"]},"percentComplete":{"type":["number","null"]},"dailyReportId":{"type":["string","null"]},"updatedAt":{"type":"string","description":"ISO 8601 timestamp (UTC)"}},"required":["id","projectId","costCodeId","workDate","qty","unit","location","percentComplete","dailyReportId","updatedAt"],"additionalProperties":false},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"secret":{"type":"string","description":"Signing secret — returned once at creation"},"createdAt":{"type":"string","description":"ISO 8601 timestamp (UTC)"}},"required":["id","url","events","active","secret","createdAt"],"additionalProperties":false}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings → API & webhooks"}}}}