{"openapi":"3.1.0","info":{"title":"Insion Content Moderation API","description":"Use the Insion API to submit content for moderation and manage the records, users, and appeals created by your integration.","version":"1.0.0"},"servers":[{"url":"https://api.insion.co","description":"Production server"},{"url":"http://localhost:3000","description":"Development Server"}],"paths":{"/api/v1/moderate":{"post":{"summary":"Moderate a record","description":"Create or update a record and return its moderation result immediately.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateRequest"}}}},"responses":{"200":{"description":"Content was moderated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModerateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ModerationProviderUnavailable"}}}},"/api/v1/ingest":{"post":{"summary":"Ingest a record","description":"Create or update a content record for asynchronous moderation. Results are delivered through webhook events when moderation is performed.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRecordRequest"}}}},"responses":{"200":{"description":"Record was created or updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRecordResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"delete":{"summary":"Delete a record","description":"Remove a record from the moderation system by its client ID.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["clientId"],"properties":{"clientId":{"type":"string","description":"Your unique identifier for the record."}}}}}},"responses":{"200":{"description":"Record was deleted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/RecordNotFound"}}}},"/api/v1/ingest/user":{"post":{"summary":"Ingest a user","description":"Create or update a user without ingesting a record.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInput"}}}},"responses":{"200":{"description":"User was created or updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestUserResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/records":{"get":{"summary":"List records","description":"List the records belonging to the authenticated organization.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"name":"clientId","in":"query","schema":{"type":"string"},"description":"Filter by your record identifier."},{"name":"user","in":"query","schema":{"type":"string"},"description":"Filter by Insion user ID."},{"name":"entity","in":"query","schema":{"type":"string"},"description":"Filter by record entity."},{"name":"status","in":"query","schema":{"type":"string","enum":["Compliant","Flagged"]},"description":"Filter by moderation status."}],"responses":{"200":{"description":"A page of records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRecordsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/records/{recordId}":{"get":{"summary":"Retrieve a record","description":"Retrieve one record by its Insion record ID.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/RecordId"}],"responses":{"200":{"description":"The requested record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/RecordNotFound"}}}},"/api/v1/users":{"get":{"summary":"List users","description":"List the users belonging to the authenticated organization.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/StartingAfter"},{"$ref":"#/components/parameters/EndingBefore"},{"name":"clientId","in":"query","schema":{"type":"string"},"description":"Filter by your user identifier."},{"name":"email","in":"query","schema":{"type":"string"},"description":"Filter by user email."},{"name":"status","in":"query","schema":{"type":"string","enum":["Compliant","Suspended","Banned"]},"description":"Filter by user action status."},{"name":"user","in":"query","schema":{"type":"string"},"description":"Filter by Insion user ID."}],"responses":{"200":{"description":"A page of users.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListUsersResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/users/{userId}":{"get":{"summary":"Retrieve a user","description":"Retrieve one user by its Insion user ID.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"}],"responses":{"200":{"description":"The requested user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/UserNotFound"}}}},"/api/v1/users/{userId}/create_appeal":{"post":{"summary":"Create an appeal","description":"Create an appeal for a suspended user. Appeals must be enabled for the organization.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/UserId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","description":"The appeal message."}}}}}},"responses":{"200":{"description":"Appeal created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAppealResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/UserNotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Provide an API key from the Insion dashboard in the Authorization header: Bearer YOUR_API_KEY."}},"parameters":{"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Maximum number of items to return."},"StartingAfter":{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Return items after this Insion ID. Cannot be used with ending_before."},"EndingBefore":{"name":"ending_before","in":"query","schema":{"type":"string"},"description":"Return items before this Insion ID. Cannot be used with starting_after."},"RecordId":{"name":"recordId","in":"path","required":true,"schema":{"type":"string"},"description":"Insion record ID."},"UserId":{"name":"userId","in":"path","required":true,"schema":{"type":"string"},"description":"Insion user ID."}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The operation is not allowed for this record or organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RecordNotFound":{"description":"The record was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UserNotFound":{"description":"The user was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"An appeal cannot be created for this user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ModerationProviderUnavailable":{"description":"Retry after the number of seconds in the Retry-After header.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"The appeal could not be created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"Content":{"oneOf":[{"type":"string","description":"Text content to moderate."},{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","description":"Text content to moderate."},"imageUrls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Image URLs to moderate."},"externalUrls":{"type":"array","items":{"type":"string","format":"uri"},"description":"External page URLs to moderate."}}}]},"Metadata":{"type":"object","description":"Custom metadata. Keys must be at most 40 characters and cannot include [ or ]. Values must be serializable, at most 500 characters, and the object can contain at most 50 keys.","additionalProperties":true},"UserInput":{"type":"object","additionalProperties":false,"required":["clientId"],"properties":{"clientId":{"type":"string","description":"Your unique identifier for the user."},"clientUrl":{"type":"string","format":"uri","description":"URL for the user's profile."},"stripeAccountId":{"type":"string","description":"The user's Stripe account ID."},"email":{"type":"string","description":"The user's email address."},"name":{"type":"string","description":"The user's name."},"username":{"type":"string","description":"The user's username."},"protected":{"type":"boolean","description":"Whether the user is protected from automated moderation actions."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"RecordInput":{"type":"object","required":["clientId","name","entity","content"],"properties":{"clientId":{"type":"string","description":"Your unique identifier for the record."},"clientUrl":{"type":"string","format":"uri","description":"URL for the original content."},"name":{"type":"string","description":"Name or title of the record."},"entity":{"type":"string","description":"Type of record, such as post, comment, or message."},"content":{"$ref":"#/components/schemas/Content"},"metadata":{"$ref":"#/components/schemas/Metadata"},"user":{"$ref":"#/components/schemas/UserInput"}}},"IngestRecordRequest":{"$ref":"#/components/schemas/RecordInput"},"ModerateRequest":{"allOf":[{"$ref":"#/components/schemas/RecordInput"},{"type":"object","properties":{"passthrough":{"type":"boolean","default":false,"description":"Moderate without persisting the record's name or content, or the user's email, name, or username."}}}]},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}},"SuccessResponse":{"type":"object","required":["message"],"properties":{"message":{"type":"string","example":"Success"}}},"IngestUserResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Insion user ID."}}}]},"IngestRecordResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["id","moderation"],"properties":{"id":{"type":"string","description":"Insion record ID."},"moderation":{"type":["string","null"],"description":"Insion moderation ID when moderation was queued; otherwise null."},"user":{"type":"string","description":"Insion user ID when a user was provided."}}}]},"ModerateResponse":{"type":"object","required":["id","status","moderation","message","flagged","categoryIds"],"properties":{"id":{"type":"string","description":"Insion record ID."},"status":{"type":"string","enum":["Compliant","Flagged"],"description":"Moderation status."},"moderation":{"type":"string","description":"Insion moderation ID."},"user":{"type":"string","description":"Insion user ID when a user was provided."},"message":{"type":"string","example":"Success"},"flagged":{"type":"boolean","description":"Deprecated. True when status is Flagged."},"categoryIds":{"type":"array","items":{"type":"string"},"description":"IDs of rules that matched the record."}}},"Record":{"type":"object","required":["id","clientId","name","entity","protected","createdAt","updatedAt","moderationPending"],"properties":{"id":{"type":"string"},"clientId":{"type":"string"},"clientUrl":{"type":["string","null"],"format":"uri"},"name":{"type":"string"},"entity":{"type":"string"},"protected":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/Metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"moderationStatus":{"type":["string","null"],"enum":["Compliant","Flagged",null]},"moderationStatusCreatedAt":{"type":["string","null"],"format":"date-time"},"moderationPending":{"type":"boolean"},"moderationPendingCreatedAt":{"type":["string","null"],"format":"date-time"},"user":{"type":["string","null"],"description":"Associated Insion user ID."}}},"RecordResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Record"}}},"ListRecordsResponse":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Record"}},"has_more":{"type":"boolean"}}},"User":{"type":"object","required":["id","clientId","protected","createdAt","updatedAt","appealUrl"],"properties":{"id":{"type":"string"},"clientId":{"type":"string"},"clientUrl":{"type":["string","null"],"format":"uri"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"username":{"type":["string","null"]},"protected":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/Metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"actionStatus":{"type":["string","null"],"enum":["Compliant","Suspended","Banned",null]},"actionStatusCreatedAt":{"type":["string","null"],"format":"date-time"},"appealUrl":{"type":["string","null"],"format":"uri"}}},"UserResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/User"}}},"ListUsersResponse":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"has_more":{"type":"boolean"}}},"CreateAppealResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","actionStatus","actionStatusCreatedAt","createdAt","updatedAt","appealUrl"],"properties":{"id":{"type":"string"},"actionStatus":{"type":["string","null"],"enum":["Compliant","Suspended","Banned",null]},"actionStatusCreatedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"appealUrl":{"type":["string","null"],"format":"uri"}}}}}}}}