> For the complete documentation index, see [llms.txt](https://docs.stellic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stellic.com/stellic-partner-api/audits/get-or-create-a-draft-of-a-published-audit.md). # Get or create a draft of a published audit Use this endpoint to change a published audit. Published audits can't be edited directly; this call returns the audit's draft, creating it the first time, and your edits go to the draft until you publish it over the original. Repeat calls return the same `draft_audit_id`, so it's safe to call at the start of every editing session. To start a new version instead, such as a new catalog year, use [`POST /programs/{program_short_name}/audits`](/stellic-partner-api/programs/create-an-audit-for-a-program.md). ## POST /audits/{audit\_id}/draft > ```json {"openapi":"3.0.0","info":{"title":"Stellic for Developers","version":"1.0"},"tags":[{"name":"Audits","description":"Read, draft, edit, and publish an audit's requirement tree. Edits go to a draft; publishing recomputes student progress in the background."}],"servers":[{"url":"https://{institution}.stellic.com/partnerapi/v1","variables":{"institution":{"default":"{institution}","description":"Your institution's Stellic subdomain: the part before `.stellic.com` in the URL you use to sign in. It becomes the host in every request, as in `https://{institution}.stellic.com/partnerapi/v1/...`. Replace the `{institution}` placeholder with your subdomain before sending."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token issued by your Stellic integration partner. Send it as `Authorization: Bearer ` on every request. One token per institution; do not share across environments."}},"schemas":{"DraftAuditResponse":{"type":"object","properties":{"success":{"type":"boolean"},"draft_audit_id":{"type":"integer","description":"Internal database ID of the draft. Use it, not the published audit's ID, on the editing endpoints."}}},"ErrorMessage":{"type":"object","description":"Error envelope used by the programs, audits, and requirements endpoints.","properties":{"error":{"type":"string","description":"Human-readable reason. Match on it if you need to branch; the strings on each endpoint page are verbatim."}}}}},"paths":{"/audits/{audit_id}/draft":{"post":{"tags":["Audits"],"parameters":[{"name":"audit_id","in":"path","required":true,"description":"Internal numeric ID of a published audit. Drafts and audits under review are rejected with 403; edit those directly.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The published audit's draft, created on this call if it did not exist yet. Repeat calls return the same `draft_audit_id` until that draft is published. Use `draft_audit_id`, not the published audit's ID, on the editing endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftAuditResponse"}}}},"400":{"description":"Audit not found or the draft could not be created right now.\n\nCommon causes:\n- No audit has this ID - returns `No Audit matches the given query.`\n- A shared requirement inside the audit is being published (also blocks returning an existing draft) - returns `['This audit uses the Shared Requirement {name} which is currently being published. Please wait until the publishing is done.']`\n- Another call is still preparing this audit's draft after a wait of up to 240 seconds - returns `[\"This audit's draft version is still being prepared. Please try again in a moment.\"]` in the string `error` field.\n- The draft could not be created or found - returns `Could not create or retrieve draft audit.`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"403":{"description":"Your IP address isn't on the allowlist for this endpoint. Contact Stellic to add it; the response includes the `client_ip` Stellic saw. Also returned, with only `error` set, when the audit isn't published (`This endpoint is only allowed for audits with published status.`) or belongs to a compliance requirement (`Compliance requirements are not available via the API.`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"client_ip":{"type":"string"}}}}}}}}}}} ``` #### What happens after the call * If there's no draft yet, one is created during the call as a copy of the published audit, named with a `-draft` suffix (`-draft-1` and so on if that name is taken). Requirements and rules get new IDs; course nodes keep theirs. * If a draft already exists, you get its ID. It may be `review` if it was sent for review. * On a regular program, the general requirements that apply to the draft are updated in the background. * Students aren't affected. The published audit stays in place until you publish the draft. #### Notes * **Edit `draft_audit_id`, not the published ID,** and read the draft with [`GET /audits/{audit_id}`](/stellic-partner-api/audits/read-an-audit.md) to get its node IDs. * **Only published audits are accepted.** A draft or under-review audit returns a 403 with `This endpoint is only allowed for audits with published status.` Edit those under their own ID. * **The call is blocked while a linked shared requirement is publishing.** It returns a 400 with `['This audit uses the Shared Requirement which is currently being published. Please wait until the publishing is done.']`, even if the draft already exists. Retry when that publish finishes. * If another call is creating this audit's draft, your call waits and returns that draft once it's ready. If you get the draft-preparation error, retry with the same published audit ID after a moment. * **There's no API call to discard a draft.** * **An unknown ID returns a 400,** `{"error": "No Audit matches the given query."}`. A compliance requirement's audit returns a 403. #### Related APIs * [`GET /programs/{program_short_name}/audits`](/stellic-partner-api/programs/list-a-program-s-audits.md) to find the published audit's ID. * [`GET /audits/{audit_id}`](/stellic-partner-api/audits/read-an-audit.md) to read the draft. * [`POST /audits/{audit_id}/publish`](/stellic-partner-api/audits/publish-a-draft-audit.md) to publish it.