Grades Exchange API | Instructure Developer Documentation Portal

Instructure Developer Documentation Portal

Get count of Grades Exchanges

get

Get the total count of Grades Exchanges (in scope of the actor credentials and the provided query parameters). Useful for determining the maximum page number of listExchanges (diving the returned number by the desired page size).

Authorizations

Query parameters

course_app_idstringOptional

statestring · enumOptionalPossible values:

Responses

200

Exchanges' count

application/json

Responseinteger

get

GET /v2/grades/exchanges/count HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Exchanges' count

Find a Grades Exchange by id

get

Get an Exchange

Authorizations

Path parameters

idstring · uuidRequired

id of the Exchange to find

Query parameters

course_app_idstringOptional

Responses

200

Exchanges response

application/json

Responseall of

404

Exchange not found

get

GET /v2/grades/exchanges/{id} HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": {
    "query": {
      "type": "assignment_scores",
      "conditions": [
        {
          "scope": "course",
          "scope_by": "id",
          "scope_id": {
            "name": "text",
            "$sys": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "source_id": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              },
              "app_id": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              },
              "created_at": "2025-06-14T12:04:45.289Z",
              "updated_at": "2025-06-14T12:04:45.289Z"
            }
          },
          "graded_after": "2025-06-14T12:04:45.289Z",
          "assignment_ids": [
            "text"
          ],
          "summary_type": "final"
        }
      ]
    },
    "metadata": {},
    "state": "created",
    "max_data_content_length": 1,
    "error_count": 1,
    "course_app_id": "text",
    "batch_exchange_id": "text"
  }
}

List Grades Exchange Errors

get

Get a list of Grades Exchange Errors

Authorizations

Path parameters

idstring · uuidRequired

id of the Exchange to list Errors

Query parameters

pageinteger · int32Optional

Specify the page number (defaults to 0)

page_sizeinteger · int32Optional

Specify the page_size (defaults to the maximum page size)

Responses

200

Exchange Errors response

application/json

Responseall of

404

Exchange not found

get

GET /v2/grades/exchanges/{id}/errors HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2025-06-14T12:04:45.289Z",
      "updated_at": "2025-06-14T12:04:45.289Z",
      "code": "query_type_not_supported",
      "message": "text",
      "details": "text"
    }
  ]
}

Get Grades Exchange Details

get

Get the details artifact for a completed Exchange. The response is a .json.gz file but it is not decompressed by the client implicitly. If no details were produced (early failure), a 404 response will be returned.

Authorizations

Path parameters

idstring · uuidRequired

id of the Exchange to get details

Query parameters

course_app_idstringOptional

Responses

200

Exchange Details response

application/octet-stream

Responsestring · binary

404

Exchange not found or the artifact is not available for it

get

GET /v2/grades/exchanges/{id}/artifacts/details HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

binary

Get Grades Exchange Consumer Logs

get

Get the consumer logs artifact for a completed Exchange. The response is a .json.gz file but it is not decompressed by the client implicitly. If no logs were produced (nothing was sent to SIS), a 404 response will be returned.

Authorizations

Path parameters

idstring · uuidRequired

id of the Exchange to get details

Query parameters

course_app_idstringOptional

Responses

200

Exchange Details response

application/octet-stream

Responsestring · binary

404

Exchange not found or the artifact is not available for it

get

GET /v2/grades/exchanges/{id}/artifacts/consumerlogs HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

binary

Get consumer details

get

Returns details about the entity designated as this Grades Application's consumer.

Authorizations

Responses

200

Consumer Details response

application/json

400

Consumer is not configured

get

GET /v2/grades/consumer HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "connector_type": "text",
  "supported_exchange_query_type": "assignment_scores",
  "summary_score_type": "final"
}

Resolve the section by ID

get

Resolves the provided Data Sync ID to an ID in the consumer's id space.

Authorizations

Path parameters

idstringRequired

Data Sync ID to resolve

Responses

200

Resolved ID response

application/json

404

ID not found

get

GET /v2/grades/sections/{id}/resolve HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "consumerSourceId": "text"
}

List Grades Schedules

get

Authorizations

Query parameters

pageinteger · int32Optional

Specify the page number (defaults to 0)

page_sizeinteger · int32Optional

Specify the page_size (defaults to the maximum page size)

Responses

200

Resolved ID response

application/json

Responseall of

404

ID not found

get

GET /v2/grades/schedules HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": [
    null,
    {
      "type": "unspecified",
      "last_executed_at": "2025-06-14T12:04:45.289Z",
      "enabled": true,
      "hour": 1,
      "days": "text",
      "metadata": {
        "created": null,
        "updated": null,
        "scheduled": null
      }
    }
  ]
}

List Grades Exchanges

get

Get a list of Grades Exchanges

Authorizations

Query parameters

pageinteger · int32Optional

Specify the page number (defaults to 0)

page_sizeinteger · int32Optional

Specify the page_size (defaults to the maximum page size)

course_app_idstringOptional

statestring · enumOptionalPossible values:

Responses

200

Exchanges response

application/json

Responseall of

get

GET /v2/grades/exchanges HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Exchanges response

{
  "data": [
    {
      "query": {
        "type": "assignment_scores",
        "conditions": [
          {
            "scope": "course",
            "scope_by": "id",
            "scope_id": {
              "name": "text",
              "$sys": {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "source_id": {
                  "ANY_ADDITIONAL_PROPERTY": "text"
                },
                "app_id": {
                  "ANY_ADDITIONAL_PROPERTY": "text"
                },
                "created_at": "2025-06-14T12:04:45.289Z",
                "updated_at": "2025-06-14T12:04:45.289Z"
              }
            },
            "graded_after": "2025-06-14T12:04:45.289Z",
            "assignment_ids": [
              "text"
            ],
            "summary_type": "final"
          }
        ]
      },
      "metadata": {},
      "state": "created",
      "max_data_content_length": 1,
      "error_count": 1,
      "course_app_id": "text",
      "batch_exchange_id": "text"
    }
  ]
}

Create a Grades Exchange

post

Create a Grades Exchange

Authorizations

Body

metadataobject | nullableOptional

Responses

200

Exchanges response

application/json

Responseall of

objectOptional

400

Bad Request

application/json

post

POST /v2/grades/exchanges HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 364

{
  "query": {
    "type": "assignment_scores",
    "conditions": [
      {
        "scope": "course",
        "scope_by": "id",
        "scope_id": {
          "name": "text",
          "$sys": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "source_id": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "app_id": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            }
          }
        },
        "graded_after": "2025-06-14T12:04:45.289Z",
        "assignment_ids": [
          "text"
        ],
        "summary_type": "final"
      }
    ]
  },
  "metadata": {}
}

{
  "data": null
}

Create Grades Exchange Errors

post

Create a list of Grades Exchange Errors

Authorizations

Path parameters

idstring · uuidRequired

id of the Exchange to create Errors

Body

idstring · uuidRead-onlyOptional

created_atstring · date-timeRead-onlyOptional

updated_atstring · date-timeRead-onlyOptional

codestring · enumOptionalPossible values:

messagestringRead-onlyOptional

detailsstringOptional

Responses

200

Exchange Errors response

application/json

Responseall of

400

Bad Request

application/json

404

Exchange not found

post

POST /v2/grades/exchanges/{id}/errors HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "code": "query_type_not_supported",
  "details": "text"
}

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2025-06-14T12:04:45.289Z",
    "updated_at": "2025-06-14T12:04:45.289Z",
    "code": "query_type_not_supported",
    "message": "text",
    "details": "text"
  }
}

Create Grades Exchange Data

post

Create Grades data for an Exchange

Authorizations

Path parameters

idstring · uuidRequired

id of the Exchange to create Data

Body

finalbooleanOptional

Responses

200

Exchanges response

application/json

Responseall of

objectOptional

400

Bad Request

application/json

404

Exchange not found

post

POST /v2/grades/exchanges/{id}/data HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2373

{
  "assignments": [
    {
      "error_code": "assignment_group_missing_name",
      "sync_status": "pending",
      "$sys": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "source_id": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "app_id": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "created_at": "2025-06-14T12:04:45.289Z",
        "updated_at": "2025-06-14T12:04:45.289Z"
      },
      "$section": {
        "name": "text",
        "$sys": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "source_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "app_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      },
      "$category": {
        "name": "text",
        "$sys": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "source_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "app_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      },
      "$term": {
        "name": "text",
        "$sys": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "source_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "app_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      },
      "name": "text",
      "description": "text",
      "points_possible": 1,
      "due_at": "2025-06-14T12:04:45.289Z",
      "available_at": "2025-06-14T12:04:45.289Z",
      "$ext": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "scores": [
        {
          "error_code": "assignment_group_missing_name",
          "sync_status": "pending",
          "$person": {
            "name": "text",
            "$sys": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "source_id": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              },
              "app_id": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            }
          },
          "$grader": {
            "name": "text",
            "$sys": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "source_id": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              },
              "app_id": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            }
          },
          "score": 1,
          "grade": "text",
          "late": true,
          "missing": true,
          "excused": true,
          "submitted_at": "2025-06-14T12:04:45.289Z",
          "preview_url": "text",
          "$ext": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ]
    }
  ],
  "summaries": [
    {
      "error_code": "assignment_group_missing_name",
      "sync_status": "pending",
      "$section": {
        "name": "text",
        "$sys": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "source_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "app_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      },
      "$person": {
        "name": "text",
        "$sys": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "source_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "app_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      },
      "$grader": {
        "name": "text",
        "$sys": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "source_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "app_id": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      },
      "summary_type": "final",
      "score_type": "raw",
      "score": 1,
      "grade": "text",
      "last_activity": "2025-06-14T12:04:45.289Z",
      "comments": [
        "text"
      ],
      "$ext": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "final": true
}

{
  "data": null
}

Create Batch Grades Exchange Error

post

Create a Batch Grades Exchange Error

Authorizations

Path parameters

idstring · uuidRequired

id of the Batch Grades Exchange to create Error

Body

codestring · enumOptionalPossible values:

Responses

200

Batch Exchange Error response

application/json

Responseall of

objectOptional

400

Bad Request

application/json

404

Exchange not found

post

POST /v2/grades/batch/{id}/error HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "code": "integration_error"
}

{
  "data": null
}

Create Grades Exchange Batch Context Data

post

Create context data for a Batch Exchange

Authorizations

Path parameters

idstring · uuidRequired

id of the Batch Exchange to create Context Data

Body

course_idsstring[]Optional

Responses

200

Batch Exchanges Context Data response

application/json

Responseall of

objectOptional

400

Bad Request

application/json

404

Batch Exchange not found

post

POST /v2/grades/batch/{id}/data HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "course_ids": [
    "text"
  ]
}

{
  "data": null
}

Update grades Schedule

patch

Update a grades schedule. Only the enabled attribute may be updated.

Authorizations

Path parameters

idstring · uuidRequired

id of the Schedule to update

Body

enabledbooleanOptional

Responses

204

No content

patch

PATCH /v2/grades/schedules/{id} HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "enabled": true
}

204

No content

Run a grades schedule

post

Enqueues a grade schedule for execution

Authorizations

Path parameters

idstring · uuidRequired

id of the schedule to be executed

Body

object | nullableOptional

Responses

204

No content

409

Conflict, when running the schedule is rejected

429

When running the schedule is rejected due to rate limiting

post

POST /v2/grades/schedules/{id}/run HTTP/1.1
Host: api.us2.kimonocloud.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content