Agents
Upload your API files
Upload API files as an alternative to scanning a connected repository. Teaflask reads the files and proposes actions for your catalog. Nothing is added without your approval.
Open Actions, choose Scan actions, then Upload manually. Select individual files or a zip. Findings appear in Waiting on you, where you can review the proposed definitions and policies before approving them. Approving an action does not grant it to an agent; see Actions.
Choose the files
OpenAPI and Swagger
Upload an OpenAPI 3 or Swagger 2.0 specification in JSON or YAML. You can upload one file, several files that reference each other, or a zip that preserves their folder structure. Include the files the specification references.
GraphQL
Upload the queries and mutations your app sends, together with the schema used to check them:
- Operation documents in
.graphqlor.gqlfiles, including any fragments they use. - The schema as SDL files (
.graphql,.gql, or.graphqls), or as one JSON introspection result.
The schema describes what the server permits. The operation documents describe what your app actually asks it to do. Both are needed to discover GraphQL actions.
You can include OpenAPI, Swagger, and GraphQL files in the same upload. Every GraphQL operation in one upload must use the same schema and endpoint path. If your app uses several GraphQL servers, upload each server's operations separately with its schema and path.
Upload limits
An upload can contain up to 1,000 files and 16 MB in total. For a zip, the limits apply to the files after extraction, not just the compressed archive.
A scan reads at most 20 OpenAPI or Swagger specification roots per upload. Check the scan result for files or operations it could not read; accepting the upload does not mean every operation became a proposal.
Enter the GraphQL path
For an upload containing GraphQL operations and their schema, the dialog asks Where does your app send GraphQL requests? Enter the path on your API, such as /graphql, then choose Upload.
Enter only the path, never a full web address. Leave out query strings, fragments, and placeholders. The path applies to every GraphQL operation in that upload.
Your actions adapter chooses the server. If GraphQL uses a different host from the rest of your API, use a request adapter that routes GraphQL actions through your app's own GraphQL client. See Adapters.
Fix an incomplete GraphQL upload
A GraphQL upload is refused when it contains:
- Operations without a schema. Add the schema and upload them together.
- A schema without operations. Add the queries and mutations your app sends; the schema alone cannot produce GraphQL actions.
- Operations with both SDL schema files and an introspection result. Supply the schema in one form, not both.
- More than one introspection result. Keep the one schema for this set of operations.
A schema without operations can accompany a valid OpenAPI or Swagger specification, but it does not produce GraphQL actions.
Upload again when your API changes
Upload the updated files to propose new actions or changes to existing uploaded actions. Uploads add to the same catalog; they do not replace it with the contents of the latest upload. An upload never proposes removing an action. Archive actions you no longer want from their action pages.
If a GraphQL endpoint path changes, upload the operations with the new path. They become proposals for new actions; archive the actions using the old path yourself.
Uploads do not overwrite actions discovered from a repository. Use a repository scan to update those actions.