> ## Documentation Index > Fetch the complete documentation index at: https://docs.timeback.com/llms.txt > Use this file to discover all available pages before exploring further. # Update external grader > Replaces the mutable fields of an external grader. If the incoming url differs from the stored one, the platform re-runs the live test call before persisting; a matching url with only a status flip skips the probe. ## OpenAPI ````yaml /openapi/learn-with-ai/platform-api.yaml put /content/1.0/external-graders/{graderId} openapi: 3.1.1 info: title: TimeBack Platform API description: >- RESTful API for the TimeBack Platform. Covers authentication, rostering, curriculum, insights, assessments, content grading, and more. version: 2026.09.10.1 servers: - url: https://platform.dev.timeback.com description: integration security: [] tags: - name: Auth description: Authentication and authorization endpoints - name: Organizations description: Organizations module contains all endpoints around organization management - name: Applications description: Applications module contains all endpoints for managing LTI applications - name: Users description: >- Users module contains all endpoints around user creation, update and consultation - name: Students description: Students module contains all endpoints around student management - name: Demographics description: >- Demographics module contains all endpoints around demographics consultation - name: Consent description: >- Initiate and query TimeBack parental consent for a student, backed by an immutable audit trail. - name: Classes description: Classes module contains all endpoints around class management - name: Courses description: Courses module contains all endpoints around course management - name: Enrollments description: Enrollments module contains all endpoints around enrollment consultation - name: CASE description: Competency and Academic Standards Exchange (CASE) 1.1 API - name: Curriculum description: Curriculum module contains endpoints for managing curriculum data - name: Competency Track description: Competency track endpoints - name: Content Grading description: >- Registration and management of graders for free-response content items — bring-your-own external graders (Tier 2) and, once shipped, platform-managed grading prompts (Tier 1). - name: Caliper description: The Caliper module contains all endpoints around Caliper Analytics - name: Insights description: Coaching insights and session analytics endpoints paths: /content/1.0/external-graders/{graderId}: put: tags: - Content Grading summary: Update external grader description: > Replaces the mutable fields of an external grader. If the incoming url differs from the stored one, the platform re-runs the live test call before persisting; a matching url with only a status flip skips the probe. operationId: putExternalGrader parameters: - name: graderId in: path description: External grader identifier (UUID) required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateExternalGraderRequest' responses: '200': description: External grader updated content: application/json: schema: $ref: '#/components/schemas/ExternalGraderResponse' '400': $ref: '#/components/responses/BadRequest5' '401': description: Missing or invalid caller identity content: application/json: schema: $ref: '#/components/schemas/ApiError4' '404': description: External grader not found content: application/json: schema: $ref: '#/components/schemas/ApiError4' '409': description: A grader with this URL is already registered content: application/json: schema: $ref: '#/components/schemas/ApiError4' '500': $ref: '#/components/responses/InternalError5' security: - CognitoUserPoolAuthorizer: - https://timeback-platform.trilogy.com/content/scope/content.write components: schemas: UpdateExternalGraderRequest: type: object description: > Body for replacing an external grader's mutable fields. Full-replace semantics — every field is required, including `authenticationCredential` (must be re-supplied even when unchanged so the platform can re-probe with plaintext). properties: url: type: string format: uri maxLength: 2048 description: HTTPS URL of the grading endpoint. Must resolve to a public host. status: $ref: '#/components/schemas/ExternalGraderStatus' authenticationType: $ref: '#/components/schemas/ExternalGraderAuthenticationType' authenticationCredential: $ref: '#/components/schemas/ExternalGraderCredential' required: - url - status - authenticationType - authenticationCredential ExternalGraderResponse: type: object description: > External grader as visible to the registering caller. `authenticationCredential` is deliberately absent — write-only material never leaves the platform. properties: id: type: string format: uuid description: Stable identifier. Content items bind to graders by this id. url: type: string format: uri description: Grading endpoint URL. authenticationType: $ref: '#/components/schemas/ExternalGraderAuthenticationType' status: $ref: '#/components/schemas/ExternalGraderStatus' dateCreated: type: string format: date-time description: ISO 8601 timestamp of registration. dateLastModified: type: string format: date-time description: ISO 8601 timestamp of the last modification. required: - id - url - authenticationType - status - dateCreated - dateLastModified ApiError4: type: object properties: error: type: string description: Error name/type message: type: string description: Human-readable error message fields: type: array description: Validation errors for specific fields items: type: object properties: field: type: string message: type: string required: - error - message ExternalGraderStatus: type: string description: Lifecycle state of an external grader enum: - active - revoked ExternalGraderAuthenticationType: type: string description: How the platform authenticates outbound calls to the grader. enum: - none - api_key ExternalGraderCredential: type: - string - 'null' writeOnly: true minLength: 1 maxLength: 16384 description: > Credential material sent on every outbound call to the grader. Must be `null` when `authenticationType` is `none`; required (non-empty string) when `authenticationType` is `api_key`. Encrypted at rest via KMS; **never returned in any response**. Wire mapping: `api_key` → `X-Api-Key: `. responses: BadRequest5: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ApiError4' InternalError5: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiError4' securitySchemes: CognitoUserPoolAuthorizer: type: oauth2 description: >- OAuth 2.0 client credentials flow. Contact timeback@trilogy.com to request credentials for your application. flows: clientCredentials: tokenUrl: https://platform.dev.timeback.com/auth/1.0/token scopes: https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly: roster readonly https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.readonly: roster-core readonly https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput: roster createput https://purl.imsglobal.org/spec/lti/v1p3/scope/lti.readonly: lti readonly https://purl.imsglobal.org/spec/or/v1p2/scope/roster-demographics.readonly: roster-demographics readonly https://timeback-platform.trilogy.com/consent/scope/consent.write: consent write https://timeback-platform.trilogy.com/consent/scope/consent.read: consent read https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.createput: roster-core createput https://purl.imsglobal.org/spec/or/v1p2/scope/roster.delete: roster delete https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.delete: roster-core delete https://purl.imsglobal.org/spec/case/v1p0/scope/case.readonly: case readonly https://purl.imsglobal.org/spec/case/v1p0/scope/case.createput: case createput https://purl.imsglobal.org/spec/case/v1p0/scope/case.delete: case delete https://timeback-platform.trilogy.com/competency-track/scope/competency-track.readonly: competency-track readonly https://timeback-platform.trilogy.com/competency-track/scope/competency-track.write: competency-track write https://timeback-platform.trilogy.com/competency-track/scope/competency-track.delete: competency-track delete https://timeback-platform.trilogy.com/content/scope/content.write: content write https://timeback-platform.trilogy.com/content/scope/content.read: content read https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write: events write https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.readonly: events readonly https://timeback-platform.trilogy.com/webhooks/scope/webhooks.write: webhooks write https://timeback-platform.trilogy.com/webhooks/scope/webhooks.read: webhooks read https://timeback-platform.trilogy.com/webhooks/scope/webhooks.delete: webhooks delete ````