openapi: 3.2.0 info: title: OpenGov Purchase Order Admin Settings API version: 1.0.0 description: API for managing purchase orders, line items, splits, and vendors. servers: - url: https://api-purchase-order.procurement.opengov.com description: Production - url: https://api-purchase-order.procurement.ogstaging.us description: Staging - url: https://api-purchase-order.procurement.ogintegration.us description: Integration security: - platformApiKey: [] - platformBearerToken: [] tags: - name: Admin Settings paths: /api/v1/po/entities/{entityId}/admin/settings: get: tags: - Admin Settings operationId: adminSettings.getSettings parameters: - name: entityId in: path schema: type: string description: The UUID of the Platform entity default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1 format: uuid pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true description: The UUID of the Platform entity responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: type: object required: - settings properties: settings: $ref: '#/components/schemas/AdminSettingsModel.json' additionalProperties: false additionalProperties: false '400': description: The request did not match the expected schema content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 400 code: type: string description: Machine-readable error code example: ValidationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: The request body failed validation. fieldErrors: type: array description: Per-field validation errors (present for 400 validation errors) items: type: object properties: parameter: type: string description: Dot-path to the field example: lineItems.0.lineItemSplits.1 detail: type: string description: Human-readable validation message example: 'Account 101-5100 has insufficient budget: requested 500.00, available 200.00' code: type: string description: Machine-readable rule identifier example: BUDGET_INSUFFICIENT data: type: object description: Structured context for the error (account codes, amounts, IDs, etc.) additionalProperties: true example: accountNumber: 101-5100 accountPseudoKey: GF-101-5100 requestedAmount: 500 availableAmount: 200 required: - parameter - detail required: - status - code - detail '401': description: AuthError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 401 code: type: string description: Machine-readable error code example: AuthenticationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: Authentication is required to access this resource. required: - status - code - detail '403': description: UnauthorizedError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 403 code: type: string description: Machine-readable error code example: AuthorizationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: You do not have permission to perform this action. required: - status - code - detail '404': description: EntityNotFoundError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 404 code: type: string description: Machine-readable error code example: PurchaseOrderNotFound detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: Purchase order with id 123 was not found. required: - status - code - detail '500': description: InfrastructureError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 500 code: type: string description: Machine-readable error code example: InternalServerError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: An unexpected error occurred while processing your request. Please try again later. required: - status - code - detail description: Returns entity-level admin settings. Creates a row with defaults (allowOverInvoicing=false, autoIssueOnPromotion=false) on first call so the response always includes id/createdAt/updatedAt. summary: Get admin settings for an entity patch: tags: - Admin Settings operationId: adminSettings.updateSettings parameters: - name: entityId in: path schema: type: string description: The UUID of the Platform entity default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1 format: uuid pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true description: The UUID of the Platform entity responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: type: object required: - settings properties: settings: $ref: '#/components/schemas/AdminSettingsModel.json' additionalProperties: false additionalProperties: false '400': description: The request did not match the expected schema content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 400 code: type: string description: Machine-readable error code example: ValidationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: The request body failed validation. fieldErrors: type: array description: Per-field validation errors (present for 400 validation errors) items: type: object properties: parameter: type: string description: Dot-path to the field example: lineItems.0.lineItemSplits.1 detail: type: string description: Human-readable validation message example: 'Account 101-5100 has insufficient budget: requested 500.00, available 200.00' code: type: string description: Machine-readable rule identifier example: BUDGET_INSUFFICIENT data: type: object description: Structured context for the error (account codes, amounts, IDs, etc.) additionalProperties: true example: accountNumber: 101-5100 accountPseudoKey: GF-101-5100 requestedAmount: 500 availableAmount: 200 required: - parameter - detail required: - status - code - detail '401': description: AuthError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 401 code: type: string description: Machine-readable error code example: AuthenticationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: Authentication is required to access this resource. required: - status - code - detail '403': description: UnauthorizedError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 403 code: type: string description: Machine-readable error code example: AuthorizationError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: You do not have permission to perform this action. required: - status - code - detail '404': description: EntityNotFoundError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 404 code: type: string description: Machine-readable error code example: PurchaseOrderNotFound detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: Purchase order with id 123 was not found. required: - status - code - detail '500': description: InfrastructureError content: application/json: schema: type: object properties: status: type: integer description: HTTP status code example: 500 code: type: string description: Machine-readable error code example: InternalServerError detail: type: string description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues). example: An unexpected error occurred while processing your request. Please try again later. required: - status - code - detail description: Creates or partially updates entity-level admin settings (upsert). Omitted fields retain their existing value or default. Returns the persisted settings. summary: Update admin settings for an entity requestBody: content: application/json: schema: type: object required: [] properties: allowOverInvoicing: type: boolean autoIssueOnPromotion: type: boolean vendorContactMandatory: type: boolean additionalProperties: false required: true components: schemas: AdminSettingsModel.json: type: object required: - id - entityId - allowOverInvoicing - autoIssueOnPromotion - vendorContactMandatory - createdAt - updatedAt properties: id: type: number entityId: type: string description: The UUID of the Platform entity default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1 format: uuid pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ allowOverInvoicing: type: boolean autoIssueOnPromotion: type: boolean vendorContactMandatory: type: boolean createdAt: $ref: '#/components/schemas/DateTimeUtc' updatedAt: $ref: '#/components/schemas/DateTimeUtc' additionalProperties: false title: AdminSettingsModel.json DateTimeUtc: type: string description: a string to be decoded into a DateTime.Utc securitySchemes: platformApiKey: description: OpenGov Platform API Key type: apiKey name: Authorization in: header platformBearerToken: type: http scheme: bearer