> ## Documentation Index > Fetch the complete documentation index at: https://docs.govly.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a workspace ## OpenAPI ````yaml /openapi/tools-v1.yaml post /api/tools/v1/workspaces openapi: 3.1.0 info: title: Govly Tools API version: 1.0.0-alpha description: > ALPHA / UNSTABLE: This API is still in active development. Endpoint behavior, request fields, response fields, error codes, and operation names may change before the Tools API is declared stable. REST-callable tool surface for agent and automation workflows. Agents are the primary consumer, but integrations can be built on this API. Responses are JSON for typed clients; MCP tools may render action results into text-oriented formats separately. Validating requests: validate against this schema in your client before sending. Govly ignores a request field it does not recognize rather than rejecting it, so a misspelled filter name is not applied — the response returns 200 with a broader result set than you intended, and nothing marks the difference. Where a request body declares `additionalProperties: false`, strict client-side validation is what catches that. Fields sent with the wrong type are rejected with 400 on most endpoints; validate types in your client too rather than relying on it. Rate limits: each resource (for example awards, opportunities, or workspaces) allows 70 requests per minute per user. Exceeding it returns 429 with the standard error envelope, `code: rate_limited`, and a `Retry-After` header. Keys sent in the `X-API-KEY` header are also subject to the Enterprise API limit of 300 requests per minute per key; see the Rate Limits page. servers: - url: https://app.govly.com security: - bearerApiKey: [] - headerApiKey: [] tags: - name: Opportunities description: Search, fetch, and inspect Govly opportunity records. - name: Awards description: Search and inspect awarded government contracts. - name: Contacts description: Search and inspect government points of contact. - name: Signals description: Search clustered procurement and market intelligence signals. - name: Places description: Resolve place names to canonical Govly Place ids. - name: Product Catalogs description: List government contract price lists and search their line items. - name: Workspaces description: Create, update, and inspect opportunity workspaces. - name: Workspace Members description: Add users and teams to workspaces. - name: Workspace Attachments description: List and upload workspace attachments. - name: Workspace Comments description: Post comments to workspaces. - name: Follows description: Follow opportunities and related workspace activity. - name: Shares description: Share opportunities, awards, and contacts with colleagues by email. - name: Saved Searches description: List saved opportunity searches and cached matches. - name: Documents description: >- Read document representations and request temporary original-file downloads. - name: Quote Submissions description: >- Inspect quote submission requirements, submit quotes, and poll submission status. - name: Inbox description: Read and triage the authenticated user's matched inbox items. paths: /api/tools/v1/workspaces: post: tags: - Workspaces summary: Create a workspace operationId: create_workspace requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: type: string primaryFocus: $ref: '#/components/schemas/PrimaryFocusInput' privateAccess: type: boolean workflowStage: type: string statusCategory: type: string status: type: string description: >- Human-readable workspace status name, status category, or legacy workflow stage. Prefer this for agent and MCP-style clients. workspaceStatusId: type: string description: >- Current-organization workspace status ID. Prefer status unless the caller already has this ID. organizationDefault: type: boolean autoFollowCreator: type: boolean responses: '201': description: Created workspace content: application/json: schema: $ref: '#/components/schemas/WorkspaceEnvelope' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/RateLimited' components: schemas: PrimaryFocusInput: type: object required: - type - id properties: type: type: string enum: - opportunity id: type: string WorkspaceEnvelope: type: object required: - data properties: data: $ref: '#/components/schemas/Workspace' meta: $ref: '#/components/schemas/ActionMeta' Workspace: type: object required: - id - name - status properties: id: type: string name: type: string description: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time commentsCount: type: integer status: type: object required: - category - label properties: id: type: string description: Exact custom workspace status ID, when assigned. category: type: string description: >- Coarse status bucket. Triage is the default for newly created workspaces. label: type: string description: >- Human-readable status name. Falls back to the category label when no custom status is set. primaryFocus: $ref: '#/components/schemas/AssociatedEntity' comments: type: array description: >- Recent comments. Only present on show/create/update responses, capped at the most recent 20. items: $ref: '#/components/schemas/Comment' attachments: type: array description: Workspace attachments. Only present on show/create/update responses. items: $ref: '#/components/schemas/WorkspaceAttachment' customFields: type: array description: >- Your organization's custom field values for this workspace, ordered by field id. Search responses include populated fields plus any explicitly filtered field, using null for an unset filtered field. Show/create/update responses include every field your organization has defined, using null for unset fields. items: $ref: '#/components/schemas/WorkspaceCustomField' ActionMeta: type: object properties: availableActions: type: array description: >- Structured hints for useful follow-up actions. These are advisory; clients should still rely on tool schemas and authorization. items: $ref: '#/components/schemas/AvailableAction' sourceCoverage: type: object description: >- Result-local source inventory and guidance for claims that require opportunity attachment content. required: - opportunityAttachmentCount - guidance properties: opportunityAttachmentCount: type: integer minimum: 0 guidance: type: string ErrorEnvelope: type: object required: - errors properties: errors: type: array items: type: object required: - status - code - title - detail properties: status: type: string code: type: string title: type: string detail: type: string source: type: object properties: pointer: type: string RateLimitError: type: object required: - error properties: error: type: string AssociatedEntity: type: object required: - type - id properties: type: type: string enum: - opportunity - award - contact id: type: string Comment: type: object required: - id - body - createdAt - attachments properties: id: type: string body: type: string description: Markdown body for the comment. attachments: type: array description: Workspace attachments tied to this comment. items: $ref: '#/components/schemas/WorkspaceAttachment' createdAt: type: string format: date-time updatedAt: type: string format: date-time WorkspaceAttachment: type: object required: - id - workspaceId - filename properties: id: type: string workspaceId: type: string commentId: type: string nullable: true filename: type: string contentType: type: string byteSize: type: integer createdAt: type: string format: date-time file: $ref: '#/components/schemas/AttachmentFile' description: >- Present only on the workspace attachments endpoint. Workspace show responses surface attachments without download metadata. WorkspaceCustomField: type: object required: - id - name - type - value properties: id: type: string description: Stable custom field id, unique within your organization. name: type: string description: Display name. Names are not guaranteed unique; use id as the key. type: type: string enum: - text - select - number - date - multiselect description: Native Workspace custom field type. value: description: >- Raw stored value, or null when the field is unset for this workspace. Shape depends on the field type (select fields store the option label as a string); keys of object-shaped values are camelized. AvailableAction: type: object required: - name - description - arguments - idPaths properties: name: type: string description: MCP/tool operation name. description: type: string arguments: type: object description: Static arguments to pass to the action. idPaths: type: array description: >- JSON paths where IDs for this action can be found in the current response. items: type: string AttachmentFile: type: object description: >- Presigned download metadata. Omitted when attachment content is unavailable or URLs are excluded. required: - url - expiresAt properties: url: type: string format: uri expiresAt: type: string format: date-time responses: Error: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: > Too many requests. Two limiters can produce this status and they use different bodies. The per-user limit of 70 requests per minute for each resource returns the standard error envelope with `code: rate_limited` and a `Retry-After` header. Keys sent in the `X-API-KEY` header are also subject to the Enterprise API limit of 300 requests per minute per key, which returns the plain `error` form with `Retry-After` and the `X-RateLimit-*` headers. Clients should accept either body. headers: Retry-After: description: Seconds to wait before retrying. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/RateLimitError' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key headerApiKey: type: apiKey in: header name: X-API-KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.